Layrz for Developers

CLAUDE.md ​

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands ​

bash
# Start dev server (localhost only)
pnpm run dev
# or
make run

# Start dev server (network accessible)
pnpm run dev:net

# Build for production (outputs to .vitepress/dist and ./dist)
pnpm run build

# Preview production build
pnpm run preview

# Lint JS and Vue files
pnpm run lint

Requires Node.js 24+ and pnpm 10.28.0.

Running pnpm in this environment ​

The user uses nvm to manage Node versions. Always activate Node 24 and use the full pnpm path:

bash
source ~/.nvm/nvm.sh && nvm use 24 && ~/.local/share/pnpm/pnpm <command>

Architecture ​

This is a VitePress documentation site for the Layrz IoT platform, deployed at https://developers.layrz.com.

Content Structure ​

Content is organized into top-level sections, each a directory of Markdown files:

  • protocol/ — Layrz Protocol spec (packets, commands, modes)
  • api/ — GraphQL APIoT reference with multi-language code snippets (snippets/ subdirectory covers JS, Python, Go, Dart, C#, PHP, etc.)
  • python/ — Python SDK docs
  • sdk/ — Layrz SDK class reference and examples
  • lcl/ — Layrz Compute Language (LCL) — a formula/expression DSL similar to Excel functions
  • lml/ — Layrz Markup Language (LML) — a markup DSL for messages/emails
  • components/ — Open source library catalog (Vue, Flutter/Dart, Python, Ruby)
  • manuals/ — Outbound integration manuals (noindex — internal use only)
  • tools/ — Online utility documentation

VitePress Configuration ​

.vitepress/config.mjs is the main config (2100+ lines). It handles navigation, sidebar, SEO <head> tags, and registers custom Shiki languages. The /manuals routes are intentionally set to noindex,nofollow via transformHead.

Custom Vue Components ​

Registered globally in .vitepress/theme/index.js and available in any Markdown file:

ComponentUsage
`<Note type="infosuccess
<Chip>Inline tag/badge
<Packet> / <PacketExample>Protocol packet visualization
<ExtraArgsExample>Parameter documentation
<DynamicCode>Code examples with live execution
<OutboundRestManual> / <OutboundQs3Manual> / <OutboundSecurityTripsEventsManual> / <OutboundAtsDocumentsRest>Full interactive manual pages (fetch content from VITE_MANUAL_URL env var)

Custom Syntax Highlighting ​

.vitepress/languages/lcl.js and .vitepress/languages/lml.js define Shiki grammar for LCL and LML code blocks. Use ```lcl and ```lml fences in Markdown.

Environment Variables ​

Copy .env.example to .env for local overrides:

  • VITE_MANUAL_URL — API endpoint for outbound manual content (default: https://api.layrz.com/manuals)

Linting ​

ESLint is configured in eslint.config.mjs using eslint-plugin-vue flat config. It targets .vitepress/**/*.{js,vue} and excludes the cache/ and dist/ directories. Opinionated formatting rules are disabled — only logic and correctness rules are enforced.

Deployment ​

GitHub Actions (.github/workflows/build-site.yaml) builds on push to main and deploys to GitHub Pages. The build artifact is .vitepress/dist.

Contributing ​

All commit messages must follow the Conventional Commits format defined in CONTRIBUTING. Key points:

  • Type must be lowercase (feat, fix, docs, chore, deps, refactor, etc.)
  • Description must be imperative mood and must not end with a period
  • A single commit can declare multiple changes in the body (each becomes a separate changelog entry)
  • Co-author lines go in the footer

See CONTRIBUTING for the full spec and examples.