---
title: "Create an app"
description: "Scaffold a blog, SaaS, or storefront template in demo or connected mode, then run and deploy it."
canonical_url: "https://docs.linguana.dev/docs/cli/create-app"
markdown_url: "https://docs.linguana.dev/docs/cli/create-app.md"
x_farming_labs_generated_preamble: true
---

# Create an app
URL: /docs/cli/create-app
LLM index: /llms.txt
Description: Scaffold a blog, SaaS, or storefront template in demo or connected mode, then run and deploy it.
Related: /docs/cli/link, /docs/cli/commands

# Create an app

`create app` writes a complete, standalone multilingual app from the template registry. Each app is ordinary source code that you own: no runtime dependency on the CLI, no generated lock-in, and an MIT license.

```bash title="terminal"
npx @linguanahq/cli create app [directory] [options]
```

## Create interactively

```bash title="terminal"
npx @linguanahq/cli create app
```

The CLI asks, in order:

1. **Choose a template**: `blog`, `saas`, or `storefront`.
2. **Choose a framework**: React, Vue, Svelte, SolidJS, or TanStack Start.
3. **Where should we create your app?** Defaults to `my-<template>`, for example `my-blog`.
4. **Package manager**: npm, pnpm, Yarn, or Bun. The default is the package manager you used to run the CLI.
5. **Connect Linguana or try a demo?** Connected mode signs you in through the browser and sets up a project; demo mode needs no account.

Options you pass on the command line skip the matching question. Press Control-C at any prompt to cancel.

## Create with options

```bash title="terminal"
npx @linguanahq/cli create app my-store --framework vue --template storefront --demo
```

| Option | Values | Purpose |
| --- | --- | --- |
| `[directory]` | Path | Where to write the app. Must be new or empty (a `.git` directory is allowed) |
| `--template <template>` | `blog`, `saas`, `storefront` | Which app to create |
| `--framework <framework>` | `react`, `vue`, `svelte`, `solidjs` (or `solid`), `tanstack-start` | Which framework variant to create |
| `--demo` | | Use bundled translations without an account |
| `--connect` | | Sign in and connect a Linguana project |
| `--package-manager <manager>` | `npm`, `pnpm`, `yarn`, `bun` | Override package-manager detection |
| `--skip-install` | | Write files without installing dependencies |

Connected mode also accepts the project options from `link`: `--organization`, `--project`, `--new-organization`, `--new-project`, `--environment`, `--locales`, and `--overwrite-env`. `--demo` cannot be combined with `--connect` or with any project provisioning option. See the [command reference](/docs/cli/commands#create-app) for the complete list.

## Demo mode

```bash title="terminal"
npx @linguanahq/cli create app my-blog --framework react --template blog --demo
cd my-blog
npm run dev
```

Demo mode includes English source content and bundled French, Spanish, and Arabic catalogs. It does not make Linguana API requests. Language selection persists in a cookie between visits, and Arabic switches the document to right-to-left.

When the app is ready, the CLI prints:

```text title="output"
Your app is ready.

  cd 'my-blog'
  npm run dev

Deployment: see DEPLOY.md in your app.
Connect later with: npx @linguanahq/cli link
```

## Connected mode

```bash title="terminal"
npx @linguanahq/cli create app my-product --framework tanstack-start --template saas --connect
```

Connected mode runs these steps after writing the app files and before installing dependencies:

1. If you are not signed in, the CLI starts [browser sign-in](/docs/cli/authentication).
2. You choose or create an organization, then choose or create a project. A new project is named after the app directory by default.
3. For a new project, you choose which languages to enable. French, Spanish, and Arabic are preselected.
4. The CLI writes `linguana.json` and an ignored `.env.local` with the project's development credentials.

The final message adds your dashboard project link. If setup is interrupted at any point, your app is already saved: run `npx @linguanahq/cli link` inside it to resume. See [Connect an existing app](/docs/cli/link) for how projects, environments, and credentials are chosen.

Connecting credentials requires Owner or Admin access to an active organization. Templates use English source content, so they must connect to a project whose source language is English. New organizations keep Linguana's billing defaults, and new projects receive development, staging, and production environments.

<ExpectedResult>
Your connected app builds and uploads its source text to the development environment of your project. Setup does not start paid translation runs or publish catalogs; those remain explicit dashboard actions. Until you publish a catalog, the app shows English source text.
</ExpectedResult>

Connected templates run with a development token and `LINGUANA_UPLOAD=true`, which also turns on [local translation preview](/docs/build-with-code/local-preview) during `npm run dev`. Selecting an enabled target language in the dev server can request preview translations under the project's per-request ceiling and your organization's monthly cap. To opt out locally, add `hotReload: false` to the `linguana()` options in `vite.config.ts`, or switch preview off in the project settings.

## What the app contains

Each variant includes:

| File | Purpose |
| --- | --- |
| `src/` | Native framework components, explicit message IDs, source fallbacks, and bundled demo catalogs |
| `vite.config.ts` | `@linguanahq/vite` with the framework adapter before the framework plugin |
| `linguana.json` | Nonsecret linkage and mode, safe to commit |
| `.env.example` | The environment contract, without credentials |
| `.gitignore` | Ignores `.env.local`, `.env.*.local`, `.linguana/`, and build output |
| `README.md` | How to run, connect, and customize the app |
| `DEPLOY.md` | Cloudflare and static or Node deployment instructions |
| `wrangler.jsonc` | Cloudflare Workers configuration |
| `ASSETS.md`, `LICENSE` | Illustration credits and the MIT license |

TanStack Start variants add `nitro.config.ts` and server rendering with request-aware locale hydration. Svelte variants add `svelte.config.js`. The `package.json` name is derived from the directory name.

Edit native components and literal messages directly. Keep explicit message IDs stable so existing translations continue to match. Build output includes `.linguana/manifest.json` for review.

## `linguana.json`

`linguana.json` contains nonsecret, versioned linkage. Commit it.

```json title="linguana.json"
{
  "schemaVersion": 1,
  "framework": "solidjs",
  "template": "blog",
  "templateVersion": "0.1.0",
  "mode": "demo",
  "apiUrl": "https://linguana-api.mohammedibrahim.dev",
  "sourceLocale": "en",
  "defaultEnvironment": "development"
}
```

After connecting, `mode` becomes `connected` and the file gains `organizationId` and `projectId`. Copying `.env.example` alone does not enable connected mode; the template reads `mode` from this file. Use `--api-url` to write a different API origin for local or self-hosted installations.

## Run, check, and build

The generated scripts are the same across package managers:

```bash title="terminal"
npm run dev          # Start the Vite development server
npm run check-types  # Type-check the app
npm run build        # Production build
```

If dependency installation fails, the app is kept. Run your package manager's install command in the app directory to retry. With `--skip-install`, install dependencies yourself before running the app.

## Deploy

Each app includes `DEPLOY.md`, `.env.example`, and Cloudflare configuration.

| Variant | Targets | Commands |
| --- | --- | --- |
| React, Vue, Svelte, SolidJS | Cloudflare Workers static assets, or any static host | `npm run build`, then publish `dist/` with SPA fallback to `index.html` |
| TanStack Start | Cloudflare Workers, or a Node server | `npm run build:cloudflare`, or `npm run build:node` then `npm start` |

Static variants deploy their `dist` directory with SPA navigation fallback, so deep links keep working. TanStack Start supports Nitro's `cloudflare_module` output and a Node server build.

For a connected production deployment, pull production credentials and configure the same variables on your build host:

```bash title="terminal"
npx @linguanahq/cli env pull --environment production
```

Configure every variable from `.env.example`, with matching private and public project and environment values. Hosting login and deployment are separate from Linguana login. Never upload `.env` files or the CLI account session, and keep `LINGUANA_TRANSLATE` set to `false` in templates; publish catalogs from the dashboard.

## Create without prompts

Supply every required choice when running in CI or scripts. `--yes` uses defaults where they exist, but never chooses connected mode for you.

```bash title="terminal"
npx @linguanahq/cli create app my-store \
  --framework vue --template storefront --demo \
  --package-manager pnpm --skip-install --yes --json
```

See [Scripts and CI](/docs/cli/automation) for defaults, JSON output, and exit codes.

<FailureGuide symptom="The destination is not empty" cause="create app only writes into a new or empty directory." check="Choose a new directory, or run npx @linguanahq/cli link inside an existing app to connect it instead." />

<NextStep>
[Connect the app to your project](/docs/cli/link), then [translate and publish a language](/docs/use-linguana/publish-language).
</NextStep>

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).