trustvid-remotion-compositions

Shared Remotion composition package used by:

• cronjobs for server-side rendering with @remotion/renderer
• trustvid-ai-platform only for runtime Remotion composition playback/imports

Why this package exists

This package was created to make Remotion composition logic a single shared runtime artifact across services.

Before this package, composition code was tied to UI source structure, which caused environment/path coupling and deployment issues (especially in cron/worker containers). Separating it into @trustvid/remotion-compositions gives one versioned source of truth for rendering behavior.

Why used in cronjobs

• Cron renders videos server-side with @remotion/renderer.
• Cron should not depend on UI repo layout or copy UI source files into images.
• A published package provides a stable, installable runtime entry (dist/remotion/index.js) for render jobs in staging/prod.

Why used in trustvid-ai-platform

• UI preview/player should use the same composition runtime as server rendering.
• Using the same package reduces drift between editor preview and final rendered output.
• Versioned package updates make behavior changes explicit and traceable across environments.

In short: UI and cron both use this package so preview and render stay aligned while deployment remains clean and reproducible.

Architecture (high-level)

                 +------------------------------------+
                 | @trustvid/remotion-compositions   |
                 |  - Remotion composition runtime   |
                 |  - dist/remotion/index.js         |
                 +-----------------+------------------+
                                   ^ 
                                   | shared runtime import
             +---------------------+----------------------+
             |                                            |
+-------------------------------+        +----------------------------------+
| trustvid-ai-platform (UI)     |        | cronjobs (worker/render service) |
| - Player preview uses package |        | - @remotion/renderer uses package|
| - Editor runtime composition  |        | - Final video render pipeline    |
+-------------------------------+        +----------------------------------+

Runtime-only scope

This package is intentionally runtime-only.

It ships only what is required to render Remotion compositions (server-side render and player/runtime composition code).

Included

• Remotion entrypoint: dist/remotion/index.js
• Composition runtime modules under:
  • dist/components/campaign-steps/video-editor/composition/
  • dist/components/campaign-steps/video-editor/components/overlays/
  • dist/components/campaign-steps/video-editor/components/VideoWithLoader.js
  • dist/components/campaign-steps/video-editor/components/AnimatedOverlay.js
  • runtime helpers used by composition (animation, media, shadow, text, preload/script utils)

Intentionally excluded (not published)

These editor/UI modules are deliberately not part of the package artifact:

• src/components/campaign-steps/editor-modal-components/**
• src/components/campaign-steps/video-editor/editor.jsx
• src/components/campaign-steps/video-editor/DraggableCanvas.jsx
• src/components/campaign-steps/video-editor/MultiTrackTimeline.jsx
• src/components/campaign-steps/video-editor/GeneratedVideoPlayer.jsx
• src/components/campaign-steps/video-editor/fieldRegistry.js
• src/components/campaign-steps/video-editor/components/Editor*.jsx
• src/components/campaign-steps/video-editor/components/fieldRenderers/**
• src/components/campaign-steps/video-editor/components/timeline/**
• src/components/campaign-steps/video-editor/hooks/useEditor*.js
• src/services/**, src/pages/**, src/helpers/**, src/contexts/**, src/constants/** (editor-era support code)

If a consumer needs full editor UI modules, they must come from trustvid-ai-platform (not this package).

Package name

@trustvid/remotion-compositions

Entry point

Published entry: dist/remotion/index.js (compiled CommonJS, CRA/Jest-safe)

Source entry: src/remotion/index.js

Versioning and release flow

npm registry env (CI and local)

Publish steps source scripts/npm-registry-env.sh before release.sh (same pattern as trustvid-ui-library / @trustvid/design-system).

• Registry URL/host default to public npm when unset.
• NPM_AUTH_TOKEN: set a default after :- in scripts/npm-registry-env.sh for temporary in-repo CI auth (rotate/remove when moving to Bitbucket variables). If Bitbucket production deployment defines NPM_AUTH_TOKEN, that value wins over the file default—clear the deployment variable to use the script default.
• Local override (gitignored): copy scripts/npm-registry-env.local.sh.example to scripts/npm-registry-env.local.sh and set NPM_AUTH_TOKEN there.

Publish steps also source scripts/bitbucket-ci-env.sh for default BITBUCKET_API_TOKEN / BITBUCKET_USERNAME (HTTPS git push for release commits), matching trustvid-ui-library. Prefer secured Bitbucket variables when you migrate off hardcoded defaults.

Bitbucket variables (optional when using defaults in npm-registry-env.sh)

• NPM_REGISTRY_URL (optional; default https://registry.npmjs.org/)
• NPM_REGISTRY_HOST (optional; default registry.npmjs.org)
• NPM_AUTH_TOKEN (optional if set as default in npm-registry-env.sh; otherwise required — token must publish @trustvid/remotion-compositions)

Pipeline behavior

• main branch:
  • step 1: validate package (lint, test, package:check)
  • step 2: auto bump + publish
• custom pipelines:
  • publish-current-version: publish current version without bump
  • release-patch: bump patch + publish + push release commit
  • release-minor: bump minor + publish + push release commit
  • release-major: bump major + publish + push release commit

All publish paths include a guard that fails fast if the same package version is already published.

release.sh runs npm whoami right after configuring ~/.npmrc. If the token is expired or invalid, the pipeline prints an explicit npm registry authentication failed message. Without that step, npm publish often shows 404 Not Found, which is easy to misread as “package missing.”

Auto bump rules on main

When BUMP_TYPE is not explicitly set, release script derives bump from latest commit message:

• #major or BREAKING CHANGE -> major
• #minor or feat(...) / feature -> minor
• default -> patch

Recommended developer workflow

1. Open PR with changes
2. Use one marker in merge/squash commit message:
   • #major, #minor, or #patch
3. Merge PR into main
4. Main pipeline bumps and publishes automatically

Alternative: run custom pipeline (release-patch|minor|major) manually.

Git push behavior in pipeline

For bump-and-publish pipelines, the release script now prefers the existing origin remote as-is:

• If origin is SSH ([email protected]:... or ssh://...), the script uses SSH push directly.
• If origin is HTTPS, the script falls back to BITBUCKET_API_TOKEN auth with username x-token-auth.

Required for bump-and-publish pipelines (release commit push):

• Preferred: Bitbucket Pipelines SSH key with write access to the repository
• Fallback for HTTPS remotes: BITBUCKET_API_TOKEN

Notes:

• SSH is the preferred setup when the repository remote is already SSH.
• For HTTPS remotes, BITBUCKET_API_TOKEN must have repository write access.
• Before version bump or publish, the script runs git push --dry-run origin HEAD and fails early if push access is not available.
• Branch restrictions must allow the pipeline identity to push the release commit.

Optional bot identity:

• RELEASE_GIT_NAME (default: trustvid-release-bot)
• RELEASE_GIT_EMAIL (default: [email protected])

Install in consumers

In cronjobs and trustvid-ai-platform:

npm install @trustvid/remotion-compositions

Ensure each consumer repo has .npmrc configured to the same private registry:

registry=${NPM_REGISTRY_URL}
//${NPM_REGISTRY_HOST}/:_authToken=${NPM_AUTH_TOKEN}

Local smoke checks before release

npm ci
npm run lint
npm run test:unit
npm run test:integration
npm run package:check

Local development

Option A (recommended for local dev): file: dependency

The file: line in package.json only tells npm where to resolve @trustvid/remotion-compositions from (a path on disk). It does not replace installing dependencies: you still run npm install in each consumer repo (trustvid-ai-platform, cronjobs) so the link is created and Remotion + React are installed. You are not “avoiding” install, you are swapping the compositions package source from the registry to your local folder.

To make this durable for local development, both consumers now run scripts/prune-linked-remotion-peers.js during postinstall and before start/build/test. That script detects a linked @trustvid/remotion-compositions package and removes nested react, react-dom, remotion, and @remotion/* copies from the linked package's node_modules so the consumer app always uses one shared React + Remotion runtime.

Use file: in local branches for fast iteration:

"@trustvid/remotion-compositions": "file:../trustvid-remotion-compositions"

Add this explicitly in both consumer repos:

• trustvid-ai-platform/package.json -> dependencies["@trustvid/remotion-compositions"]
• cronjobs/package.json -> dependencies["@trustvid/remotion-compositions"]

// trustvid-ai-platform/package.json
"dependencies": {
  "@trustvid/remotion-compositions": "file:../trustvid-remotion-compositions"
}

// cronjobs/package.json
"dependencies": {
  "@trustvid/remotion-compositions": "file:../trustvid-remotion-compositions"
}

IMPORTANT: Local-only override. Do not commit this file: value. Before raising/merging a PR, switch both repos back to a published version (for example ^0.1.1).

Then install in each consumer repo:

npm install

This install now also runs the linked-package prune step automatically in both consumers.

When do you need npm install inside trustvid-remotion-compositions? Only if you work on this repo directly: npm run build, npm run build:watch, npm run test:unit, or npm run test:integration need Babel, pinned react/react-dom, and the same Remotion version as consumers (see below). If you only pull already-built dist/ and never run scripts here, consumer-only npm install can be enough, but shape/composition changes always require a build from this repo.

Remotion single version (required): Remotion throws if it detects more than one version (e.g. 4.0.428 in the app and 4.0.441 under trustvid-remotion-compositions/node_modules). This package and every consumer must use the exact same remotion, @remotion/player, @remotion/renderer, @remotion/bundler, etc. (pinned in this repo’s package.json). After changing versions, run npm install in the compositions repo and again in each consumer, then verify:

npx remotion versions

Local dev loop:

cd trustvid-remotion-compositions
npm install   # once, or after package.json / lock changes
npm run build
# optional watch mode
npm run build:watch

After rebuilding package dist/, restart consumer dev servers as needed.

If you run npm install again inside trustvid-remotion-compositions, that repo will recreate its own local runtime dependencies for package development and tests. That is fine: the consumer postinstall / pre* prune step will remove the linked duplicates again before UI or cron use the package.

PR/CI guard for file: dependency

trustvid-ai-platform and cronjobs now include a CI check that fails if @trustvid/remotion-compositions is committed as file:....

So local file: usage is supported, but PR branches must switch back before merge.

Required for staging/prod and merged branches

Use published version:

"@trustvid/remotion-compositions": "^0.1.1"