---
name: add-new-package
description: Add a new package to the Remotion monorepo, including package scaffolding, monorepo registration, documentation, build scripts, tests, and release checklist updates. Use when creating a new @remotion package.
---

# Add a new Remotion package

## Steps

1. **Create `packages/<name>/`** with these files:
   - `package.json` — copy from `@remotion/light-leaks` as template; update name, description, homepage, dependencies
   - `tsconfig.json` — extends `../tsconfig.settings.json`, uses tsgo with `emitDeclarationOnly: true`, `outDir: "dist"`, `module: "es2020"`, `moduleResolution: "bundler"`, `target: "ES2022"`
   - `src/index.ts` — exports
   - `bundle.ts` — Bun build script, externalize `react`, `remotion`, `remotion/no-react`, `react/jsx-runtime`, `react/jsx-dev-runtime`, `react-dom`
   - `eslint.config.mjs` — use `remotionFlatConfig({react: true})` if React, `{react: false}` otherwise
   - `.npmignore` — copy from `@remotion/light-leaks`
   - `README.md` — package name, description, install command, link to docs

2. **Register in monorepo:**
   - `tsconfig.json` (root) — add `{"path": "./packages/<name>"}` to references
   - `packages/cli/src/list-of-remotion-packages.ts` — add `'@remotion/<name>'`
   - `packages/create-video/src/list-of-remotion-packages.ts` — add `'@remotion/<name>'`
   - `packages/studio-shared/src/package-info.ts` — add to `packages`, `descriptions`, `installableMap`, `apiDocs`

3. **Documentation (`packages/docs/docs/<name>/`):**
   - Add `"@remotion/<name>": "workspace:*"` to `packages/docs/package.json` dependencies (needed for twoslash snippets)
   - `index.mdx` — install tabs, table of contents, license
   - `table-of-contents.tsx` — TOCItem grid linking to component/function pages
   - Individual component/function `.mdx` pages
   - Edit `packages/docs/sidebars.ts` — add category
   - Edit `packages/docs/components/TableOfContents/api.tsx` — import table of contents and add section

See the `writing-docs` skill for details on writing documentation.

4. **Example usage:**
   - Add `"@remotion/<name>": "workspace:*"` to `packages/example/package.json`
   - Create `packages/example/src/<Name>/index.tsx`
   - Register `<Composition>` in `packages/example/src/Root.tsx`
   - Add `{"path": "../<name>"}` to `packages/example/tsconfig.json` references

5. **Run `bun i`** to install dependencies

6. **Build:** `cd packages/<name> && bun run make`

## Version

Use the current version from `packages/core/src/version.ts`.  
For the documentation version, increment the patch version by 1 as it will only be released with the next Remotion release.

## Patterns

- Use `"workspace:*"` for internal dependencies
- Use `"catalog:"` for shared external dependency versions
- The `make` script is: `tsgo && bun --env-file=../.env.bundle bundle.ts`
- Add `"type": "module"` to `package.json`
- Add `"@typescript/native-preview": "catalog:"` to devDependencies
- Types/main point to `dist/index.d.ts` and `dist/index.js` (not `dist/cjs/`)
- Packages with React components need `peerDependencies` for `react` and `react-dom`