@localess/nuxt

localess-js

Official JavaScript/TypeScript SDK monorepo for the Localess headless CMS platform.

Overview

Localess is a headless CMS designed for teams that need flexible content management with multi-locale support, a Visual Editor, and a developer-friendly API. This repository houses all official JavaScript and TypeScript integrations as a single npm workspaces monorepo.

Keeping all packages together in one repository ensures that shared types and interfaces remain consistent, changes to the core SDK are immediately reflected in framework-specific packages, and versioning stays synchronized across the entire SDK surface. All packages share one version number (lockstep semver).

Packages

Package Dependency Graph

                       ┌──▶ @localess/model
@localess/react   ─────┼──▶ @localess/client ──▶ @localess/model, @localess/live-preview
@localess/angular ─────┤
@localess/vue     ─────┼──▶ @localess/richtext ──▶ @localess/model
@localess/svelte  ─────┤
@localess/astro   ─────┴──▶ @localess/live-preview ──▶ @localess/model

@localess/nuxt    ────────▶ @localess/vue

                       ┌──▶ @localess/model
@localess/cli     ─────┼──▶ @localess/client ──▶ @localess/model, @localess/live-preview
                       └──▶ @localess/schema ──▶ @localess/model

@localess/model is the root of the graph and depends on nothing. @localess/richtext, @localess/schema, and @localess/live-preview depend only on @localess/model; @localess/client depends on @localess/model and @localess/live-preview. The framework packages depend on @localess/client, @localess/model, @localess/richtext, and @localess/live-preview; @localess/cli depends on @localess/client, @localess/model, and @localess/schema. Dependent packages never depend on each other, with one sanctioned exception: @localess/nuxt wraps @localess/vue. See docs/decisions/ for the reasoning behind these boundaries.

Quick Start

Choose the package that fits your use case:

Server-side / Framework-agnostic

npm install @localess/client

import { localessClient } from "@localess/client";

const client = localessClient({
  origin: 'https://my-localess.web.app',
  spaceId: 'YOUR_SPACE_ID',
  token: 'YOUR_API_TOKEN', // Keep secret — server-side only (public read-only tokens are safe client-side)
});

const content = await client.getContentBySlug('home');
const translations = await client.getTranslations('en');

→ See the full @localess/client documentation

React (including Next.js, React Router, TanStack Start)

npm install @localess/react

import { localessInit, LocalessComponent } from "@localess/react";

localessInit({
  origin: process.env.LOCALESS_ORIGIN,
  spaceId: process.env.LOCALESS_SPACE_ID,
  token: process.env.LOCALESS_TOKEN,
  enableSync: true,
  components: { 'hero': HeroBlock, 'footer': Footer },
});

→ See the full @localess/react documentation

Angular

npm install @localess/angular

import { provideLocaless } from "@localess/angular";

export const appConfig: ApplicationConfig = {
  providers: [
    provideLocaless({
      origin: 'https://my-localess.web.app',
      spaceId: 'YOUR_SPACE_ID',
      token: 'YOUR_PUBLIC_TOKEN',
      enableSync: true,
    }),
  ],
};

→ See the full @localess/angular documentation

Vue (including Nuxt)

npm install @localess/vue

import { createApp } from "vue";
import { Localess } from "@localess/vue";

createApp(App)
  .use(Localess, {
    origin: import.meta.env.VITE_LOCALESS_ORIGIN,
    spaceId: import.meta.env.VITE_LOCALESS_SPACE_ID,
    token: import.meta.env.VITE_LOCALESS_TOKEN, // public token only
    components: { page: PageComponent, button: ButtonComponent },
    enableSync: true,
  })
  .mount('#app');

→ See the full @localess/vue documentation

Svelte (including SvelteKit)

npm install @localess/svelte

<script lang="ts">
  import { localessInit } from "@localess/svelte";

  localessInit({
    origin: import.meta.env.VITE_LOCALESS_ORIGIN,
    spaceId: import.meta.env.VITE_LOCALESS_SPACE_ID,
    token: import.meta.env.VITE_LOCALESS_TOKEN, // public token only
    components: { page: Page, button: Button },
    enableSync: true,
  });
</script>

→ See the full @localess/svelte documentation

Astro

npm install @localess/astro

// astro.config.mjs
import { defineConfig } from "astro/config";
import { localess } from "@localess/astro";

export default defineConfig({
  integrations: [
    localess({
      origin: process.env.LOCALESS_ORIGIN,
      spaceId: process.env.LOCALESS_SPACE_ID,
      token: process.env.LOCALESS_TOKEN,
      enableSync: true,
    }),
  ],
});

→ See the full @localess/astro documentation

Schema as code

npm install @localess/schema

import { defineConfig, defineEnum, defineSchema, type InferContentData } from "@localess/schema";

const Size = defineEnum({
  id: 'Size',
  displayName: 'Size',
  values: [{ name: 'Small', value: 'small' }, { name: 'Large', value: 'large' }],
});

const Page = defineSchema({
  id: 'Page',
  type: 'ROOT',
  displayName: 'Page',
  fields: [
    { name: 'title', kind: 'TEXT', required: true },
    { name: 'size', kind: 'OPTION', source: Size }, // by-value ref, normalized to 'Size'
  ],
});

export const config = defineConfig({ schemas: [Size, Page] });
export type Content = InferContentData<typeof config>;

→ See the full @localess/schema documentation

CLI (Translations, Type Generation & Schemas)

npm install @localess/cli -D

localess login
localess translation pull en --path ./locales/en.json
localess type generate
localess schema validate ./localess.config.ts

→ See the full @localess/cli documentation

Repository Structure

localess-js/
├── packages/
│   ├── model/           # @localess/model
│   ├── client/          # @localess/client
│   ├── richtext/        # @localess/richtext
│   ├── live-preview/    # @localess/live-preview
│   ├── schema/          # @localess/schema
│   ├── react/           # @localess/react
│   ├── angular/         # @localess/angular
│   ├── vue/             # @localess/vue
│   ├── nuxt/            # @localess/nuxt
│   ├── svelte/          # @localess/svelte
│   ├── astro/           # @localess/astro
│   └── cli/             # @localess/cli
├── playgrounds/         # Example apps per framework (next, react-router, tanstack-start,
│                        # angular-ssr, angular-static, analog, nuxt, svelte-kit, astro,
│                        # schema, and their static variants)
├── docs/                # Project reference and architectural decision records (ADRs)
├── package.json         # Workspace root (npm workspaces)
└── LICENSE

Development

Requirements

• Node.js >= 24.0.0
• npm >= 10 (for workspaces support)

Install Dependencies

npm install

Build All Packages

# Build all packages in dependency order
# (model, live-preview, richtext, client, schema, react, vue, svelte, cli, angular, astro, nuxt)
npm run build

# Build individual packages
npm run build:model
npm run build:live-preview
npm run build:richtext
npm run build:client
npm run build:schema
npm run build:react
npm run build:vue
npm run build:svelte
npm run build:cli
npm run build:angular
npm run build:astro
npm run build:nuxt

@localess/model must be built before running the client, richtext, or schema tests; @localess/live-preview before building @localess/client; @localess/richtext before the framework package tests; @localess/schema before the CLI tests; @localess/vue before building @localess/nuxt.

Run Tests

All packages have test suites (vitest everywhere, including @localess/angular via Angular CLI's unit-test builder):

npm test

# Run a single package's tests
npm test --workspace=@localess/angular
npm run test:cli

# Run a single test file
npx vitest run packages/cli/src/commands/login/login.test.ts

Playgrounds

# Angular SSR playground (requires build:angular first)
npm run start:angular-ssr

# Angular SSG / static-prerender playground (requires build:angular first)
npm run start:angular-static

# AnalogJS playgrounds — SSR and static (require build:angular first)
npm run start:analog
npm run start:analog-static

Other playgrounds under playgrounds/ are regular npm workspaces — run them with npm run dev --workspace=<name>; see each playground's README.

AI Coding Agents

Each package ships a SKILL.md file that directs AI coding agents (GitHub Copilot, Claude Code, Cursor, and others) to accurate, up-to-date APIs, patterns, and best practices for that package — instead of relying on potentially outdated training data.

SKILL files

Using SKILL files in your project

SKILL.md is shipped inside each npm package, so it is available locally in node_modules after installation. Reference it from your project's AGENTS.md to ensure your agent reads accurate Localess documentation every session:

## Localess

Refer to the following SKILL files for accurate API usage, patterns, and best practices:

- @node_modules/@localess/client/SKILL.md
- @node_modules/@localess/react/SKILL.md
- @node_modules/@localess/schema/SKILL.md
- @node_modules/@localess/cli/SKILL.md

Include only the packages your project uses. The @ prefix is the syntax used by most agent tools (GitHub Copilot, Claude Code, Cursor) to import file contents inline into the agent context.

Keeping SKILL files up to date

When you make changes to a package's public API, options, behaviour, or best practices, update the corresponding SKILL.md alongside your code change:

• New option or parameter → add it to the relevant options table and usage example
• Changed behaviour → update the description and any affected code snippets
• Deprecated API → mark it clearly and point to the replacement
• New command or subcommand (CLI) → add a full entry with all flags and examples

Documentation

• docs/index.md — project reference: packages, hard rules, build & test, code style
• docs/decisions/ — architectural decision records (the WHY behind the hard constraints)
• CHANGELOG.md — release notes
• CLAUDE.md — contributor guide for humans and AI agents working in this repo

Contributions are welcome! Please open an issue or pull request on GitHub.

License

MIT © Lessify