Installation
Installing @timelinx packages, peer dependencies, TypeScript requirements, and framework-specific setup
Package Overview
| Package | Purpose | Peer dependencies |
|---|---|---|
@timelinx/core | Headless engine, types, dispatch, tools, serializers | None |
@timelinx/react | Hooks, context, TimelineEngine class | react >=18, @timelinx/core |
@timelinx/ui | React components, CSS design system | react >=18, @timelinx/react, @timelinx/core |
@timelinx/media-web | Browser media adapters | react >=18, @timelinx/core (not on npm yet) |
Installing
Recommended for most apps. Includes Core, React bindings, and UI components.
pnpm add @timelinx/core @timelinx/react @timelinx/uiRequirements
- TypeScript >=5.0 - the packages use
constenums, branded types, andsatisfies. - Node.js >=22 - for local development and CI.
- React >=18 -
@timelinx/reactusesuseSyncExternalStorewhich landed in React 18.
CSS Setup
@timelinx/ui ships with a CSS design system. You must import two files:
Choose a preset
Import one preset to define the color tokens:
@import '@timelinx/ui/styles/presets/dark-pro'; /* default dark theme */
/* @import '@timelinx/ui/styles/presets/light'; */
/* @import '@timelinx/ui/styles/presets/high-contrast'; */Import structure
Import the structure CSS to define layout and component styles:
@import '@timelinx/ui/styles/structure';Import order matters
Always import the preset before structure. The structure CSS references CSS variables defined by the preset. Reversing the order causes unstyled components.
The components will not render correctly without both imports. If you see unstyled or missing UI, this is the most common cause.
Next.js Setup
@timelinx/ui and @timelinx/react are ES modules. Add them to transpilePackages in next.config:
const nextConfig = {
transpilePackages: ['@timelinx/ui', '@timelinx/react', '@timelinx/core'],
};
export default nextConfig;All components that use hooks must be rendered client-side. Add 'use client' to any file that imports TimelineEditor, TimelineProvider, or hooks:
'use client';
import { TimelineEditor } from '@timelinx/ui';
import { TimelineEngine } from '@timelinx/react';Import the CSS in app/globals.css:
@import '@timelinx/ui/styles/presets/dark-pro';
@import '@timelinx/ui/styles/structure';Vite Setup
No special configuration is needed. Vite handles ES modules and CSS imports natively.
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
});Checking Your Setup
After installation, verify everything is working with this minimal test:
'use client'; // if using Next.js
import { TimelineEngine } from '@timelinx/react';
import { TimelineEditor } from '@timelinx/ui';
import { createTimelineState, createTimeline, frameRate, toFrame } from '@timelinx/core';
const engine = new TimelineEngine({
initialState: createTimelineState({
timeline: createTimeline({
id: 'tl-test',
name: 'Test',
fps: frameRate(30),
duration: toFrame(900),
}),
}),
});
export default function TestPage() {
return (
<div style={{ height: 400 }}>
<TimelineEditor engine={engine} />
</div>
);
}If the editor renders with a toolbar and empty track area, the installation is complete.