Skip to main content

Scaffold a New Project

unlayer init creates a new project directory with the email editor pre-wired for your framework. Pick from five official starter templates and the CLI handles install, configuration, and (optionally) connecting the project to your Unlayer account.

Syntax​

unlayer init [project-name] [options]

Description​

init creates a new project directory, copies an official starter template, installs dependencies (unless --no-install), and optionally connects the project to your Unlayer account.

Run it with no arguments for the interactive flow. The CLI prompts you for a name, framework, and starter template.

Arguments​

ArgumentDescription
[project-name]Name of the project (and the directory it's created in)

Options​

FlagDescription
-f, --framework <framework>Framework to use (see supported frameworks)
-t, --template <template>Starter template (see starter templates)
--no-installSkip installing dependencies
--no-typescriptDisable TypeScript (enabled by default)
--skip-connectSkip account connection after scaffolding
--workspace-id <id>Workspace ID to connect (non-interactive)
--project-id <id>Project ID to connect (non-interactive)
-o, --output-dir <dir>Directory to create the project in (defaults to cwd)
--jsonOutput as JSON

Supported Frameworks​

ValueStack
nextjsNext.js 15 (App Router) with React
vite-reactVite + React
vite-vueVite + Vue 3
nuxtNuxt 3
vanillaPlain HTML + JS, no build step

Starter Templates​

ValueDescription
adventureAdventure — travel newsletter
productProduct — Apple-style announcement
blankBlank — start from scratch

Examples​

unlayer init
# → prompts for name, framework, template, account connection

Specify everything inline​

unlayer init my-email-app -f nextjs -t product

Skip dependency install (you'll run it later)​

unlayer init my-app -f vite-react --no-install
cd my-app
pnpm install   # or npm/yarn

The auto-installer detects your package manager (pnpm → yarn → npm; first one available wins) and runs it inside the new project directory with a 5-minute timeout. Install errors are non-fatal: init reports them and keeps going.

CI-friendly — fully non-interactive​

In non-interactive mode (CI or --non-interactive), all three of <project-name>, --framework, and --template are required. To also auto-connect to your account, supply both --workspace-id and --project-id.

unlayer init my-app \
  -f nextjs \
  -t blank \
  --workspace-id 42 \
  --project-id 17 \
  --json

Plain JS, no TypeScript, no editor connection​

unlayer init landing-page -f vanilla -t blank --no-typescript --skip-connect

What init Creates​

For a Next.js scaffold:

my-app/
├── app/
│   ├── editor/
│   │   └── page.tsx       # Embedded Unlayer editor
│   ├── layout.tsx
│   └── page.tsx           # Landing page
├── public/
│   └── designs/
│       └── sample.json    # Starter design (adventure / product / blank)
├── output/
│   └── .gitkeep           # Default output directory for `unlayer pull`
├── .gitignore
├── package.json
├── tsconfig.json
├── unlayer.config.json    # Project config — see below
└── README.md

Other frameworks have their own conventional layouts (Vite + React, Vite + Vue, Nuxt, vanilla HTML). All of them get the same init-managed additions: a starter design at designs/sample.json (or public/designs/sample.json for non-vanilla), output/, .gitignore, and unlayer.config.json.

unlayer.config.json written by init​

{
  "$schema": "https://unlayer.com/cli/config-schema.json",
  "projectId": null,
  "defaults": {
    "outputDir": "./output"
  }
}

projectId starts as null and is filled in automatically when init connects the project to your Unlayer account (interactive prompt or --workspace-id + --project-id flags). Once set, subsequent CLI commands run inside this directory know which project to operate on.

One thing worth flagging: init's default outputDir is ./output (created with a .gitkeep). The CLI's fallback default — used when there's no unlayer.config.json — is ./templates. So unlayer pull inside an init-created project lands in ./output/, but a one-off unlayer pull outside a project lands in ./templates/.

After init​

cd my-app
npm run dev          # or pnpm/yarn

The dev URL depends on the framework. Next.js and Nuxt default to http://localhost:3000, Vite to http://localhost:5173, and vanilla has no dev server (open index.html directly). For Next.js the embedded editor is at /editor.

If you let init connect the project to your Unlayer account (interactive prompt or --workspace-id + --project-id), projectId is set in unlayer.config.json. Subsequent CLI commands run inside this directory pick it up:

unlayer template list      # lists templates in this project
unlayer pull               # pulls templates into ./output/

See Also​