@remotion/codemodsv4.0.527

Edit Remotion source in memory. Discover nodes, insert elements, edit props and animations, and manage composition registrations.

warning

Draft API: This API is not yet stable. We are in the experimental phase of this package and reserve to change it at any time.

The package accepts file paths and source code and returns the files that changed. It does not read or write the filesystem, execute the project, download media, or install packages. You control how changes are previewed, saved, and compiled.

Installation

Remotion CLI
npm
bun
pnpm
yarn

npx remotion add @remotion/codemods

npm i --save-exact @remotion/codemods@4.0.539

This assumes you are currently using v4.0.539 of Remotion.
Also update remotion and all `@remotion/*` packages to the same version.
Remove all ^ character in front of the version numbers of it as it can lead to a version conflict.

pnpm i @remotion/codemods@4.0.539

bun i @remotion/codemods@4.0.539

yarn --exact add @remotion/codemods@4.0.539

Keep the version aligned with the other Remotion packages in the project.

Project model

A CodemodProject contains the following properties.

rootDir

The project's root directory, used to resolve imports and file paths.

files

A Record<string, string> mapping file paths to source code. Paths may be project-relative or absolute, but must consistently identify files within the project. Include the project files needed to resolve imported components.

project.ts
import type {CodemodProject} from '@remotion/codemods';

export const project: CodemodProject = {
  rootDir: '/',
  files: {
    'src/Root.tsx': `import {Composition} from 'remotion';
import {Video} from './Video';
export const Root = () => <Composition id="Demo" component={Video} width={1920} height={1080} fps={30} durationInFrames={90} />;`,
    'src/Video.tsx': `export const Video = () => <div style={{opacity: 1}}>Hello</div>;`,
  },
};

Include the files needed for the edit. A prop edit needs its target file; resolving an imported composition component also needs the files along the import path. Mutations leave the input project unchanged.

Creating elementsv4.0.530

Describe elements with createElement() and insert it with addElement(). Elements are immutable descriptions: methods such as withProp() and withChild() return new elements. Imports and local names are resolved when the element is inserted.

insert.ts
import {addElement, applyCodemodChanges, createElement, type CodemodProject} from '@remotion/codemods';

declare const project: CodemodProject;

const solid = createElement({
  component: 'Solid',
  importPath: 'remotion',
  props: {width: 1920, height: 1080, color: 'gray'},
});
const sequence = createElement({
  component: 'Sequence',
  importPath: 'remotion',
  props: {from: 30},
}).withChild(solid);

const result = addElement({
  project,
  element: sequence,
  target: {type: 'composition', compositionFile: 'src/Root.tsx', compositionId: 'Demo'},
});
const nextProject = applyCodemodChanges(project, result.changes);
console.log(nextProject.files, result.insertedNode);

Elements can also be inserted inside, before, or after an existing node, and wrapNode() wraps an existing node in an element.

Editing a nodev4.0.528

Find a node, inspect the properties you want to edit, and pass its reference to a mutation.

edit.ts
import {applyCodemodChanges, getNodes, getNodeProps, updateNodeProps, type CodemodProject} from '@remotion/codemods';

declare const project: CodemodProject;

const node = getNodes({project, filePath: 'src/Video.tsx'}).find((candidate) => candidate.tagName === 'div');

if (node) {
  const {props} = getNodeProps({project, node, keys: ['style.opacity']});
  if (props['style.opacity'].status === 'static') {
    const result = updateNodeProps({
      project,
      node,
      props: {'style.opacity': 0.5},
    });
    const nextProject = applyCodemodChanges(project, result.changes);
    console.log(nextProject.files, result.updatedNode);
  }
}

Node referencesv4.0.528

A NodeReference contains the following properties.

filePath

The file containing the node.

nodePath

The SequenceNodePath identifying the element in the current source snapshot. Obtain it from getNodes(), an insertion result, or a mounted layer's nodePathInfo.sequenceSubscriptionKey.nodePath. Treat its contents as opaque. To traverse the tree, compare it with the parentNodePath that getNodes() returns for each node.

A reference identifies source, not a particular rendered instance. Editing a component used by several compositions changes that shared component. Editing a node inside a loop changes the source used by every iteration.

Keeping references after edits

Node and registration mutations return nodePathRemappings. Each entry contains filePath, oldNodePath, and newNodePath. Apply a mapping once to references from the input project, matching both the file and old path. A null old path means insertion; a null new path means removal. An omitted reference keeps its path.

Use insertedNode, insertedNodes, or updatedNode when returned instead of trying to reconstruct a path. Adding hooks, duplicating elements, changing wrappers, or moving registrations can move other nodes as well. After manual source changes, discover nodes again.

Editors that keep mounted sequences attached to their source nodes, such as <Canvas>, accept these mappings through queueSequenceNodePathRemappings().

Effect referencesv4.0.528

An EffectReference extends a node reference with effectIndex, the zero-based position in its inline effects array. getNodeProps() inspects effects, and effect mutations return insertedEffect, insertedEffects, or updatedEffect where applicable.

Adding, deleting, duplicating, or reordering effects can shift effect indices. Node-path remappings do not remap effect indices. Inspect the updated effects before reusing other effect references.

Mutation results

Every mutation returns a CodemodResult, synchronously or through a promise as documented on its page.

changes

An array of CodemodFileChange objects.

filePath

The changed file's key in the input project's files map, or the path of a newly created file.

previousContents

The previous source, or null if the file was created.

nextContents

The next source, or null if the file was deleted.

nodePathRemappingsv4.0.528

Node, effect, keyframe, and registration mutations return these mappings in addition to the shared result. Registration mutations return them since v4.0.530. See node references.

Applying changes

Use applyCodemodChanges() to produce a new project. The function checks every previousContents value before applying any changes, throws if a file has changed since the codemod ran, and preserves other project fields. An empty changes array returns the input project.

For undo and redo, store the file changes as one transaction. Swap previousContents and nextContents to undo it, and apply the original changes to redo it. Apply changes in the reverse order when undoing multiple transactions.

Supported edits

Code must be valid JavaScript or TypeScript with supported JSX structures. Prop inspection distinguishes static values, recognized keyframes, and computed expressions. The package does not evaluate arbitrary JavaScript. The props form of prop updates rejects computed values; structured updates permit explicit replacement. Setting a recognized keyframed prop to a static value replaces its animation.

Registration edits use explicit composition files and static IDs. They support Composition, Still, and Folder from remotion, including aliased and namespace imports. Component insertion and resolution support additional import patterns, as documented on their pages.

CodemodValue represents serializable strings, numbers, booleans, null, arrays, and objects. Strings are values, not executable expressions; use staticFileValue() to reference a file in the public folder. updateNodeProps() also accepts undefined to remove a property.

Unsupported edits throw or reject without mutating the input project. Batch operations resolve their references against the same input snapshot. Unrelated source formatting and comments are preserved; edited regions use the surrounding source style.