DEV Community

Cover image for Stop Stale Render Plans Before They Reach Remotion
Ryan Gallagher
Ryan Gallagher

Posted on

Stop Stale Render Plans Before They Reach Remotion

Stop Stale Render Plans Before They Reach Remotion

You ship a 40-second product demo. Frame timing is perfect. Motion is smooth. The compiler passed, CI went green, and your remote cache gave you a three-second build.

Then a designer opens the export: yesterday's logo is burned into every frame. The recipe file changed two commits ago, but the render plan came from last week's cache artifact. No type error. No build failure. Just a silent, perfectly consistent mistake.

That's the integration risk I'd address first when adopting video-shotcraft. Its description spans 124 shot recipes, 150 motion previews, beat synchronization, sound design, a Motion Workbench, and editable export. Those capabilities introduce several representations of the same creative intent—recipe cards, preview state, Remotion compositions, export manifests. Keeping them synchronized matters more than shaving milliseconds off local compilation.

This is a proposed integration architecture based on that description, not a claim about the repository's current implementation.

One Dependency Direction, From Recipe to Render

Put a typed contract between recipe selection and every downstream consumer:

Recipe assets → validated render plan → Remotion composition → export adapters

The contracts package owns identifiers and serializable plan shapes. A planning package resolves recipes into frame-based decisions. Remotion components consume those decisions without importing editor state. Export adapters translate the same plan into their destination formats.

The critical restriction is directional: contracts never import the planner, and the planner never imports the workbench. Otherwise, a convenient shared helper closes a cycle—the workbench imports the planner, the planner imports a composition registry, that registry imports workbench defaults. Incremental compilation now depends on partially available declarations. Adding more cache rarely fixes that dependency error.

Asset dependencies need equally explicit treatment. A recipe file can change rendering behavior without changing any TypeScript source. If it's absent from the task hash, a remote cache can return a perfectly consistent artifact for the wrong inputs.

A Small, Executable Boundary

The following scaffold runs in a new directory, not inside an existing checkout. It demonstrates the integration boundary without assuming video-shotcraft's internal paths. Copy relevant recipe and preview metadata into assets/ when adapting it.

mkdir shotcraft-boundary && cd shotcraft-boundary
mkdir -p packages/contracts/src apps/render-plan/src assets
printf '%s\n' '{"version":1}' > assets/catalog.json

cat > package.json <<'EOF'
{
  "name": "shotcraft-boundary",
  "private": true,
  "packageManager": "npm@10.9.2",
  "workspaces": ["packages/*", "apps/*"],
  "scripts": {
    "build": "turbo run build",
    "typecheck": "turbo run typecheck"
  },
  "devDependencies": {
    "turbo": "2.5.6",
    "typescript": "5.8.3"
  }
}
EOF

cat > turbo.json <<'EOF'
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["assets/**"],
  "globalEnv": ["VIDEO_FPS", "VIDEO_WIDTH", "VIDEO_HEIGHT"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "$TURBO_ROOT$/tsconfig.base.json"
      ],
      "outputs": ["dist/**"],
      "env": ["NODE_ENV"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "$TURBO_ROOT$/tsconfig.base.json"
      ],
      "outputs": []
    }
  }
}
EOF

cat > tsconfig.base.json <<'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "declaration": true,
    "noEmitOnError": true,
    "forceConsistentCasingInFileNames": true
  }
}
EOF

cat > packages/contracts/package.json <<'EOF'
{
  "name": "@shotcraft/contracts",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  }
}
EOF

cat > apps/render-plan/package.json <<'EOF'
{
  "name": "@shotcraft/render-plan",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@shotcraft/contracts": "0.0.0"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  }
}
EOF

for directory in packages/contracts apps/render-plan; do
  cat > "$directory/tsconfig.json" <<'EOF'
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}
EOF
done

cat > packages/contracts/src/index.ts <<'EOF'
type Digit = "0" | "1" | "2" | "3" | "4"
  | "5" | "6" | "7" | "8" | "9";

export type StrictShotId<S extends string> =
  string extends S ? never :
  S extends `shot-${Digit}${Digit}${Digit}` ? S : never;

export function shotId<const S extends string>(
  value: S & StrictShotId<S>
): S {
  return value;
}
EOF

cat > apps/render-plan/src/index.ts <<'EOF'
import { shotId } from "@shotcraft/contracts";

export const openingShot = shotId("shot-024");

// @ts-expect-error Identifiers require exactly three digits.
shotId("shot-24");
EOF

npm install
VIDEO_FPS=30 VIDEO_WIDTH=1920 VIDEO_HEIGHT=1080 npm run build
npm run typecheck
Enter fullscreen mode Exit fullscreen mode

What the Hash Actually Protects

Turborepo computes task hashes from source inputs, dependency tasks, the shared compiler configuration, asset contents, and declared environment variables. Remote caching reuses that identity after configuring a compatible cache service and credentials. It does not discover missing dependencies.

The deliberately broad assets/** dependency favors correctness over hit rate. Editing one preview invalidates unrelated builds. Once the integration works, split assets by consumer and narrow task inputs. Do not narrow them before understanding which files each task reads.

The Failure Behind the Boundary

Consider a reconstructed production incident: a team encodes an entire nested recipe language as recursive conditional types. As recipes grow, compiler memory spikes. A cross-package import cycle simultaneously makes declaration availability depend on build order.

The tempting response is a larger heap and another clean build. That only hides the architecture.

Break the cycle first. Then replace unbounded type-level parsing with bounded compile-time checks and runtime validation at file-loading boundaries. StrictShotId checks literal syntax, not catalog membership—"shot-999" still needs a runtime lookup. Its thousand possible identifier forms are intentional, finite work.

For diagnosis, run tsc --extendedDiagnostics on the affected package and compare instantiation counts and memory before and after simplification. Avoid claiming improvement from elapsed time alone: a warm task cache can conceal the compiler entirely.

The scaffold also avoids TypeScript incremental state initially. Turborepo restores complete dist artifacts, including declarations, while ^build establishes package order. Compiler-level incremental builds can follow once their state files have explicit ownership.

That trade-off is conservative: slightly more compilation on cache misses, substantially fewer ambiguous states. For a cinematic pipeline, predictability beats discovering during export that the plan and the pictures came from different revisions.


The hardest question isn't whether to cache aggressively—it's deciding which inconsistencies you'll tolerate when the cache lies. Do you accept stale assets in development if production always rebuilds from scratch? Do you invalidate everything on any recipe change, even when only metadata shifted? How do you verify that a three-second cached build is actually correct, not just fast?

What's your tolerance threshold for silent correctness failures in a creative pipeline?

Top comments (1)

Collapse
 
alexshev profile image
Alex Shev •

A render plan needs the same freshness controls as a deployment plan. I’d bind it to the source revision, asset hashes, composition schema version, and a bounded validity window, then reject it when any input resolves differently. That prevents a successful render from becoming evidence for a video that no longer corresponds to the approved edit.