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.

npx @linguanahq/cli create app [directory] [options]

Create interactively

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

npx @linguanahq/cli create app my-store --framework vue --template storefront --demo

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 for the complete list.

Demo mode

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:

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

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.
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 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.

Connected templates run with a development token and LINGUANA_UPLOAD=true, which also turns on local translation 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:

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.

{
  "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:

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.

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:

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.

npx @linguanahq/cli create app my-store \
  --framework vue --template storefront --demo \
  --package-manager pnpm --skip-install --yes --json

See Scripts and CI for defaults, JSON output, and exit codes.