Create a spa

A spa module is a standalone Vite single-page application that lives inside your project but runs on its own dev server. It is not part of the backend. The spa:create generator pulls the spa source from the upstream skeleton repository, marks the module as a spa in its yml config, links it to a design module, assigns a free dev port, and installs the spa dependencies. When it finishes you have a working frontend you can start with one command. If you are new to spa modules, read the spa overview first. This page is the walkthrough; for the terse flag reference see spa:create.

CLI command

talos spa:create [options]

Run it with no flags and it prompts for everything it needs: the spa name and the design module.

Examples

# Interactive: prompts for the spa name and design module
talos spa:create

# Provide the name as a flag
talos spa:create --name=dashboard

# Link the spa to a design module
talos spa:create --name=dashboard --design=ui

Options

Option	Description	Default
`--name`	Spa name. Normalized to PascalCase with any trailing `Module` stripped; the module folder uses its kebab-case form.	Prompted if omitted
`--design`	Design module the spa uses. An existing design can be chosen interactively, or a new name is scaffolded.	Prompted if omitted
`--cwd`	Project directory the spa is created in.	Current working directory
`--silent`	Suppress prompts, spinners, and output.	`false`

The command clones the spa source and installs packages, so it needs git and network access. If either is unavailable the create will not complete.

The design link

Every spa composes a design module, a type: "design" module that holds the shared UI building blocks. During create you choose which one. If your project already has type: "design" modules, you pick one interactively or pass it with --design. Otherwise, give a name that does not exist yet and the generator scaffolds it for you with design:create. The choice is recorded as design: in the spa’s yml config, so the link between the spa and its design module is explicit and persistent.

What happens

When you run spa:create, the generator works through these steps in order:

Scaffold the base module

A base module is scaffolded under modules/<kebab-name>/, using the kebab-case form of the name you gave.

Detach it from the backend

A spa is a frontend, not part of the backend, so it is un-registered from AppModule and SharedModule, and its root tsconfig path alias is removed.

Remove the backend module class

The scaffolded <Pascal>Module.ts and its spec file are deleted; a spa does not ship a backend module class.

Mark it as a spa

The module yml is marked type: "spa" and records design: "<kebab>" for the design module you chose.

Add Vite scripts and assign a port

Vite dev, build, and preview scripts are added to the module package.json. The dev script gets a free dev port: 3030 by default, or the next free port if 3030 is taken (the generator scans other modules’ --port usage to find a free one).

Clone the spa source

The upstream skeleton-spa repo is cloned (shallow) into the module’s src/, and every shared/ sub-layer is ensured to exist via .gitkeep: assets, components, hooks, layouts, services, store, styles, types, and utils.

Install dependencies

The spa’s dependencies and devDependencies are installed into the project.

Scaffold the design module if needed

If the design module you chose does not exist yet, it is scaffolded via design:create.

What you get

You end up with a self-contained spa module under modules/<kebab-name>/: its own Vite setup, a src/ populated from the skeleton, the full shared/ layer in place, a dedicated dev port, and a recorded link to its design module. See the spa structure for a tour of the generated layout.

Start and stop the spa

Run the spa from the project root with app:start. Use --modules/--packages (aliases, comma-separated module names) to narrow the run to just the spa:

# Start just one spa by name
talos app:start --modules=dashboard

# Run the spa alongside an api module it talks to
talos app:start --modules=dashboard,app

Vite serves the spa on the port assigned at create time. The spa is a frontend dev server, not a Docker service, so to stop it you interrupt the running process with Ctrl+C.

Running talos app:start with no flag starts the spa together with every other discovered module (api, microservice, storybook, swagger), which is handy when the spa needs a live backend.

Next steps

Run the dev server

Start the spa from the project root with talos app:start --modules=<name>. Vite serves it on the assigned port.

Add features

Build out pages and flows with spa:feature:create.

To take the spa back out, see remove a spa.

Use with Claude and Codex

The generator ships a matching spa:create skill. It runs the scaffold and then guides your AI agent through what comes next: choosing or naming the design module, starting the dev server, and adding the first features. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator and runs it:

Prompt

Create a spa called dashboard that uses the ui design module.

talos agent:skills:create

Then ask Codex in natural language. It maps the request to the generator and runs it:

Prompt

Create a spa called dashboard that uses the ui design module.

For example, the prompt above maps to spa:create --name=dashboard --design=ui. For the full command reference, see spa:create.

Getting Started

AI

Framework

Command Line

Create a spa

CLI command

Examples

Options

The design link

What happens

What you get

Start and stop the spa

Next steps

Run the dev server

Add features

Use with Claude and Codex

​CLI command

​Examples

​Options

​The design link

​What happens

​What you get

​Start and stop the spa

​Next steps

Run the dev server

Add features

​Use with Claude and Codex

CLI command

Examples

Options

The design link

What happens

What you get

Start and stop the spa

Next steps

Use with Claude and Codex