@effing/dev

Dev server and build tooling for Effing projects.

Part of the Effing family — programmatic video creation with TypeScript.

Reduces an Effing project to just the function modules and a config file. effing dev boots a preview app for browsing your images, annies, and effies during development; effing build bundles a simple HTTP server that can serve them in production.

Installation

npm install -D @effing/dev

Or scaffold a starter project with everything wired up:

npm create @effing my-app

Configuration

Create an effing.config.ts at the root of your project:

import { defineConfig } from "@effing/dev";

export default defineConfig({
  project: "my-app",
  images: "app/images/*.fn.tsx",
  annies: "app/annies/*.fn.tsx",
  effies: "app/effies/*.fn.tsx",
});

Glob patterns can be strings or arrays. Each matched file should export a function module (see @effing/fn). The file's basename — without .fn.tsx — becomes the module's ID, so app/images/social-card.fn.tsx registers as social-card.

Options

Environment

The dev server reads .env, .env.local, .env.development, .env.development.local from the project root and merges them into process.env (existing values take precedence).

CLI

effing dev

Starts the dev server.

npx effing dev

The dev server gives you:

• Overview page listing every image, annie, and effie in the project.
• Preview pages per module, with selectable resolutions and auto-reload when fn files change.
• Raw artifact URLs (.bytes, .tar, .json) for piping output into other tools.
• Signed-segment endpoints matching what the production server serves, so URLs built via fnUrl work identically in dev and prod.

If @effing/ffs is installed and ffs is enabled, an FFS sidecar is auto-spawned at startup.

effing url

Prints a signed fn URL for the given props — handy for agents or curl fetching a specific propped variant without going through the HTML preview pages.

npx effing url <kind> <id> --props '{"text":"Hello"}' --width 1080 --height 1080

Reads BASE_URL and SECRET_KEY from .env files in the project root.

effing manual

Prints a tool-level reference for the CLI and fn module shape — designed to be piped into an agent's context so it knows how to drive the project.

npx effing manual

The output is resolved against your config: it picks up your project's glob directories, dev resolutions, and the right package-manager invocation form (pnpm exec, yarn, npx --no, or a direct ./node_modules/.bin/effing path).

effing build

Bundles a production HTTP server to dist/server.js.

npx effing build

The bundle statically imports every fn module matched by your config and wires them into an HTTP listener via @effing/fn/server. Run with:

BASE_URL=https://your.app SECRET_KEY=... node dist/server.js

Project Structure

A typical Effing project looks like this:

my-app/
├── effing.config.ts
├── app/
│   ├── images/
│   │   └── social-card.fn.tsx
│   ├── annies/
│   │   └── intro.fn.tsx
│   └── effies/
│       └── promo.fn.tsx
└── package.json

Each *.fn.tsx file exports a function module (runner, propsSchema, previewProps). See @effing/fn for the module shape.

API

defineConfig(config)

Identity helper for effing.config.ts with full TypeScript inference.

import { defineConfig } from "@effing/dev";

export default defineConfig({
  project: "my-app",
  images: "app/images/*.fn.tsx",
});

Related Packages

• @effing/fn — Function module runtime (used by both dev and build)
• @effing/ffs — FFmpeg renderer for effie compositions
• @effing/effie-preview — Preview components used by the dev UI
• @effing/create — Scaffold a new Effing project