---

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.

---

Packages

Package	Version	Description
@localess/client	3.4.0	Core JavaScript/TypeScript SDK. Fetch content, translations, and assets from the Localess API. Server-side only.
@localess/react	3.4.0	React integration. Dynamic component mapping, rich text rendering, and Visual Editor sync.
@localess/angular	3.4.0	Angular integration. Components, directives, pipes, and Visual Editor sync.
@localess/cli	3.4.0	Command-line interface. Manage translations and generate TypeScript types from your content schemas.

Package Dependency Graph

@localess/react   ──┐
@localess/angular ──┼──▶ @localess/client (core SDK)
@localess/cli     ──┘

@localess/client is the foundational layer. @localess/react, @localess/angular, and @localess/cli depend on it for API communication, caching, and shared type definitions. The three dependents never depend on each other.

---

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
});

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

→ See the full @localess/client documentation

---

React (including Next.js)

npm install @localess/react

import { localessInit, getLocalessClient, 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 { provideLocalessBrowser } from "@localess/angular/browser";

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

→ See the full @localess/angular documentation

---

CLI (Translations & Type Generation)

npm install @localess/cli -D

localess login
localess translations pull en --path ./locales/en.json
localess types generate

→ See the full @localess/cli documentation

---

Repository Structure

localess-js/
├── packages/
│   ├── client/          # @localess/client
│   ├── react/           # @localess/react
│   ├── angular/         # @localess/angular
│   └── cli/             # @localess/cli
├── 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
npm run build

# Build individual packages
npm run build:client
npm run build:react
npm run build:cli
npm run build:angular

Run Tests

All four 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

---

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/client	packages/client/SKILL.md
@localess/react	packages/react/SKILL.md
@localess/angular	packages/angular/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/angular/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

---

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

---

License

MIT © Lessify