---
title: "Quickstart with code"
description: "Extract your first strings, then connect the app to a published language."
canonical_url: "https://docs.linguana.dev/docs/getting-started/quickstart"
markdown_url: "https://docs.linguana.dev/docs/getting-started/quickstart.md"
x_farming_labs_generated_preamble: true
---

# Quickstart with code
URL: /docs/getting-started/quickstart
LLM index: /llms.txt
Description: Extract your first strings, then connect the app to a published language.

# Quickstart with code

Add Linguana to an existing React app on Vite and confirm that its text is extracted. For other frameworks, use the [matching adapter and runtime](/docs/getting-started/frameworks); for server rendering, use [TanStack Start](/docs/getting-started/tanstack-start).

## 1. Install the packages

```bash title="terminal"
bun add @linguanahq/react @linguanahq/catalog
bun add --dev @linguanahq/vite
```

The public `0.1.0` packages ship TypeScript source. Add `--configLoader runner` to your Vite commands, preserving existing type checks:

```json title="package.json — merge with existing scripts"
{
  "scripts": {
    "dev": "vite --configLoader runner",
    "build": "vite build --configLoader runner",
    "preview": "vite preview --configLoader runner"
  }
}
```

## 2. Add the plugin before React

Merge this into your existing Vite configuration. Keep the other plugins your app uses.

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { linguana } from "@linguanahq/vite";
import { react as linguanaReact } from "@linguanahq/vite/react";

export default defineConfig({
  plugins: [
    linguana({
      adapter: linguanaReact(),
      projectId: "my-app",
      environment: "development",
      sourceLocale: "en",
      upload: false,
    }),
    react(),
  ],
});
```

`my-app` is a local identifier. Replace it with your dashboard project ID before uploading.

## 3. Wrap the application once

Use your existing `App` import and root element:

```tsx title="src/main.tsx"
import { createRoot } from "react-dom/client";
import { LocaleProvider } from "@linguanahq/react";
import { App } from "./app";

createRoot(document.getElementById("root")!).render(
  <LocaleProvider
    projectId="my-app"
    environment="development"
    initialLocale="en"
    fallbackLocale="en"
  >
    <App />
  </LocaleProvider>,
);
```

Text in components beneath the provider stays readable without a remote catalog. You do not need translation keys for static JSX.

## 4. Build and inspect the strings

```bash title="terminal"
bun run build
```

Open `.linguana/manifest.json` and find a visible string from your app. Run your app and confirm it still renders the source language. This build has not uploaded, translated, or published anything.

## 5. Connect your first language

Follow [Connect hosted translations](/docs/getting-started/connect-your-app) to create a project, replace the local identifier, upload a build, enable a language, translate it under a spending limit, and publish a catalog. Your runtime's project and environment must match the published release.

<SecurityNote>
Store `LINGUANA_PROJECT_TOKEN` only in the build environment. The browser uses a publishable key; never give a provider the project token or prefix that token with `VITE_`.
</SecurityNote>

<ExpectedResult>
The local manifest contains your app's strings and the source page still works. After the hosted steps, selecting a published language displays its translations, with source text as fallback.
</ExpectedResult>

<FailureGuide symptom="The first build fails" cause="The config loader, framework plugin order, or runtime setup is incomplete." check="Use --configLoader runner, put linguana() before the framework plugin, and follow the matching runtime setup in Install Linguana." />

<NextStep>
[Connect hosted translations](/docs/getting-started/connect-your-app), then [edit strings](/docs/use-linguana/edit-strings).
</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).