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	Version	Description
`@localess/model`	4.0.2	Shared domain-model types (content, assets, links, references, rich text, locales, spaces, translations, schemas). Zero dependencies.
`@localess/client`	4.0.2	Core JavaScript/TypeScript SDK. Fetch content, translations, and assets from the Localess API. Server-side only, unless used with a public token.
`@localess/richtext`	4.0.2	Framework-neutral rich text model and HTML renderer for Localess's TipTap JSON content. Zero dependencies.
`@localess/live-preview`	4.0.2	Framework-neutral Visual Editor bridge: sync script loading, `data-ll-*` editable attributes, editor events, sync controller. Used by every framework package.
`@localess/schema`	4.0.2	Programmatic schema definitions (`defineSchema`, `defineEnum`, `defineField`, `defineConfig`) with TypeScript content type inference. Zero dependencies.
`@localess/react`	4.0.2	React integration (incl. Next.js, React Router, TanStack Start). Dynamic component mapping, rich text, Visual Editor sync.
`@localess/angular`	4.0.2	Angular integration. Components, directives, pipes, services, and Visual Editor sync.
`@localess/vue`	4.0.2	Vue 3 integration (incl. Nuxt). Plugin, components, composables, Vite plugin, and Visual Editor sync.
`@localess/nuxt`	4.0.2	Nuxt module wrapping `@localess/vue`. Config-driven setup, public/secret token split, component auto-registration, server client.
`@localess/svelte`	4.0.2	Svelte 5 integration (incl. SvelteKit). Context init, components, actions, stores, and Visual Editor sync.
`@localess/astro`	4.0.2	Astro integration. Astro Integration entry, native `.astro` components, and Visual Editor live preview.
`@localess/cli`	4.0.2	Command-line interface. Manage translations, generate TypeScript types, and pull/push/diff/validate schemas.

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

Package	SKILL file
`@localess/model`	`packages/model/SKILL.md`
`@localess/client`	`packages/client/SKILL.md`
`@localess/richtext`	`packages/richtext/SKILL.md`
`@localess/live-preview`	`packages/live-preview/SKILL.md`
`@localess/schema`	`packages/schema/SKILL.md`
`@localess/react`	`packages/react/SKILL.md`
`@localess/angular`	`packages/angular/SKILL.md`
`@localess/vue`	`packages/vue/SKILL.md`
`@localess/nuxt`	`packages/nuxt/SKILL.md`
`@localess/svelte`	`packages/svelte/SKILL.md`
`@localess/astro`	`packages/astro/SKILL.md`
`@localess/cli`	`packages/cli/SKILL.md`

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

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.claude/skills		.claude/skills
.github		.github
docs		docs
packages		packages
playgrounds		playgrounds
scripts		scripts
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
skills-lock.json		skills-lock.json

Navigation Menu

Uh oh!

Repository files navigation

localess-js

Overview

Packages

Package Dependency Graph

Quick Start

Server-side / Framework-agnostic

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

Angular

Vue (including Nuxt)

Svelte (including SvelteKit)

Astro

Schema as code

CLI (Translations, Type Generation & Schemas)

Repository Structure

Development

Requirements

Install Dependencies

Build All Packages

Run Tests

Playgrounds

AI Coding Agents

SKILL files

Using SKILL files in your project

Keeping SKILL files up to date

Documentation

License

About

Releases

Sponsor this project

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

localess-js

Overview

Packages

Package Dependency Graph

Quick Start

Server-side / Framework-agnostic

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

Angular

Vue (including Nuxt)

Svelte (including SvelteKit)

Astro

Schema as code

CLI (Translations, Type Generation & Schemas)

Repository Structure

Development

Requirements

Install Dependencies

Build All Packages

Run Tests

Playgrounds

AI Coding Agents

SKILL files

Using SKILL files in your project

Keeping SKILL files up to date

Documentation

License

About

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Contributors

Languages