Skip to Content
Getting Started

Getting Started

This guide walks you from zero to a rendered canvas, a first edit, and an exported image in under five minutes. You will need:

  • Node.js ≥ 20.19
  • A Chromium-based browser (Chrome, Edge, Brave, Arc) — for the studio. The CLI itself runs anywhere Node runs.

1. Scaffold a project

npm create lerret@latest my-canvas

The scaffolder downloads from npm and writes a new project at ./my-canvas/. Total install — including Vite and React, downloaded once and cached — typically runs in under a minute on a warm broadband connection. No global install is required.

If my-canvas already exists, the scaffolder refuses to overwrite a non-empty directory but is happy to populate an empty one.

What you got

my-canvas/
└── .lerret/
    ├── README.md
    ├── config.json
    ├── _fonts/
    │   └── LerretFixtureMono.woff2
    ├── intro/
    │   ├── config.json
    │   └── welcome.md
    ├── landing/
    │   ├── about-vars.md
    │   └── landing-hero.jsx
    ├── social/
    │   ├── about-data-files.md
    │   ├── og-card.jsx
    │   ├── og-card.data.json
    │   ├── tw-banner.jsx
    │   └── tw-banner.data.json
    ├── brand/
    │   ├── about-validation.md
    │   ├── business-card.jsx
    │   └── business-card.data.json
    └── live/
        ├── about-live-refresh.md
        ├── config.json
        ├── clock.jsx
        ├── clock.config.json
        ├── counter.jsx
        └── counter.config.json

This is the five-page teaching preset: each page demonstrates one Lerret concept — intro (a welcome note), landing (cascading vars), social (data files + variants), brand (props schemas + validation), and live (auto-refreshing artboards). Each page ships a short about-*.md note that renders on the canvas and explains what that page teaches.

The .lerret/ folder is the only thing Lerret cares about. Everything else in the project is yours — Lerret never touches files outside it (the separation invariant).

PathWhat it is
.lerret/config.jsonProject-root config. The vars block flows down the cascade as CSS-like variables.
.lerret/_fonts/Reserved folder. Any .woff2 / .woff / .ttf / .otf here is auto-registered as a CSS @font-face rule. Available to every asset by its file name.
.lerret/social/A page — top-level non-underscore folders become pages on the canvas.
*.jsxEach component file becomes an artboard. The default export is the primary variant; named exports become extra variants.
*.data.jsonCo-located data file for an asset (here, og-card.data.json). Overrides component props at runtime.
*.config.json (next to an asset)Co-located per-asset config — e.g. clock.config.json sets an autoRefresh interval.

Want a minimal start?

For an empty project — just .lerret/config.json with { "vars": {} }, no sample assets:

npm create lerret@latest my-canvas --no-samples

Want a themed starting point?

Instead of the teaching preset, scaffold one of seven ready-made kits with --preset:

npm create lerret@latest my-canvas --preset producthunt

Valid names: acme (brand starter kit), appstore (App Store screenshots), producthunt (launch assets), social-media (six social formats), talks (conference slides), personal (personal-site assets), and live (auto-refresh demos). An unknown name errors with the valid list. There is also --demo, which scaffolds the default teaching preset and immediately starts the dev server with the first-run walkthrough (--demo is mutually exclusive with --preset and --no-samples).

2. Start the studio

cd my-canvas
npx @lerret/cli@latest dev

The Vite dev server boots and your default browser opens to the studio. You should see the five teaching pages on the canvas — a welcome note, a landing hero, social cards (an OG card plus an X banner in three variants), a business card, and two live auto-refreshing demos — each artboard rendered at its real pixel dimensions.

Common flags

npx @lerret/cli@latest dev --port 4000   # custom port (default: Vite's default, usually 5173)
npx @lerret/cli@latest dev --no-open     # don't auto-open the browser
npx @lerret/cli@latest dev --folder ./   # explicit project folder (bypasses walk-up)

If you do not pass --folder, the CLI walks up from the current working directory looking for the nearest .lerret/ — like git walks up looking for .git/.

3. Edit a component

Open .lerret/landing/landing-hero.jsx in your editor. Find the headline and change it:

// Before
<div style={{ fontSize: 76, lineHeight: 1.04, ... }}>
  Designs are just files.
</div>
 
// After
<div style={{ fontSize: 76, lineHeight: 1.04, ... }}>
  Hello from my first Lerret canvas
</div>

Save the file. The landing-hero artboard re-renders in under a second. No page reload, no manual rebuild. The watcher detects the change, Vite’s React Fast Refresh swaps the module, and the canvas updates in place.

The social and brand assets keep their text in co-located .data.json files instead of the JSX — open .lerret/social/og-card.data.json, change the headline, and save for the same sub-second loop. Step 6 covers how that works.

4. Add a second asset

Create a new file .lerret/social/release-card.jsx:

export const meta = {
  dimensions: { width: 1200, height: 630 },
  label: 'Release card',
  tags: ['release', 'og'],
};
 
export default function ReleaseCard() {
  return (
    <div style={{
      width: '100%',
      height: '100%',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      background: 'var(--brandColor, #B85B33)',
      color: 'white',
      fontSize: 72,
      fontWeight: 800,
      fontFamily: 'system-ui',
    }}>
      v1.0 — Shipping today
    </div>
  );
}

Save it. A new artboard appears on the canvas — at exactly 1200×630 — alongside the others. The watcher reports an add event, the loader incorporates the new asset into the project model, and the canvas adds the artboard.

Notice the var(--brandColor, #B85B33). The project-root config.json declares vars.brandColor = "#B85B33", which the studio exposes as a CSS custom property on the artboard. Change the value in config.json — say to "#3D5A80" — save, and every artboard re-renders with the new color.

5. Add a variant

Variants are extra components in the same file, exported by name. Add this to release-card.jsx:

export const Dark = () => (
  <div style={{
    width: '100%',
    height: '100%',
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    background: '#0A0A0A',
    color: '#E0FBFC',
    fontSize: 72,
    fontWeight: 800,
    fontFamily: 'system-ui',
  }}>
    v1.0 — Shipping today
  </div>
);

Save. A second artboard appears next to the original — labelled Dark — also at 1200×630. The meta export is shared across all variants in the file; the default export is the primary variant; each named function export is an extra variant.

Component-valued exports = variants. Non-function exports (constants, the meta object) are ignored.

6. Add data

Lerret can supply props to your component from a co-located data file — no code change required.

Create .lerret/social/release-card.data.json:

{
  "default": {
    "label": "v1.0 — Shipping today"
  },
  "Dark": {
    "label": "v1.0 — Shipping today (dark mode)"
  }
}

Then accept label as a prop in your component:

export default function ReleaseCard({ label = 'Untitled' }) {
  return (
    <div style={{ /* ... */ }}>
      {label}
    </div>
  );
}

The top-level keys match your variant export names (default, Dark), so each variant gets its own data. This is per-variant data keying. If the top-level keys do not match any export name, the entire data object is applied as shared data to every variant.

There is also a .data.js form when you need computed or conditional data — see Authoring Assets for the full mechanics.

7. Export to image files

When you are happy with the canvas, render every artboard to image files from the command line:

npx @lerret/cli@latest export

By default, output goes to ./lerret-export/ (relative to your CWD, never inside .lerret/). Each artboard becomes a PNG — including one per variant and one per Markdown note — nested under folders that mirror the project’s page/group structure. The social page from the walkthrough comes out as:

lerret-export/
├── brand/ …
├── landing/ …
├── live/ …
└── social/
    ├── about-data-files.png
    ├── og-card.png
    ├── release-card.png
    ├── release-card-Dark.png
    ├── tw-banner.png
    ├── tw-banner-Maker.png
    └── tw-banner-Talk.png

The intro page is absent by design: its config.json sets "excludeFromExport": true, a page-level flag that keeps canvas-only notes out of your export.

Useful flags:

npx @lerret/cli@latest export --format jpg     # JPG instead of PNG (jpeg also accepted)
npx @lerret/cli@latest export --out ./assets   # custom output directory
npx @lerret/cli@latest export --flat           # all images at one level, no nested folders
npx @lerret/cli@latest export .lerret/social   # scope: only this page

The CLI boots a headless Chromium through Playwright and uses the same rendering path the in-studio export buttons use, so a @lerret/cli export run produces a pixel-faithful match to what the studio captures.

See CLI Reference for the full flag list, including the --data and --config override flags that let you re-render an entire project with different data or theming without modifying any files.

What’s next

  • Concepts — the mental model: pages, groups, variants, the four-tier prop cascade.
  • Authoring Assets — the full guide to writing components, schemas, data files, and fonts.
  • Examples — sixteen runnable patterns to copy and adapt: OG cards, YouTube thumbnails, repo cards, release graphics, more.
  • CLI Reference — every flag and exit code for dev and export.
  • Deployment — local CLI, hosted browser, or self-hosted static studio.

Welcome to Lerret.

IntroductionConcepts