Sveltia CMS Dev 🛠️

🔗 Related cheat sheets:

• 🧠 Sveltia CMS: sveltia-cms.md
• 🧱 Sveltia + Hugo: sveltia-hugo.md
• 🚀 Hugo core: hugo.md
• 🧾 Hugo Markdown: hugo_markdown.md
• 🎨 Hugo themes & addons: hugo_themes-and-addons.md

Goal: fast local dev and build workflow for /home/dv/sveltia-cms.

⚡ Quickstart dev loop

From your shell:

cd /home/dv/sveltia-cms
pnpm install        # first time only
pnpm dev            # start dev server

Dev server:

• URL: http://localhost:55151/
• Config: vite.config.js → server.port = 55151, strictPort = true, host = ‘0.0.0.0’.

Common scripts (package.json):

• pnpm dev → Vite dev server.
• pnpm build → library build to package/dist.
• pnpm build:watch → watch build.
• pnpm test / pnpm test:watch → vitest test runs.
• pnpm test:coverage → vitest with coverage.
• pnpm check → runs all lint/format checks.

🏗️ Build pipeline (library mode)

Key pieces (vite.config.js):

• Entry: src/lib/main.js
• Outputs (Rollup):
  • sveltia-cms.js (IIFE) → for
  • sveltia-cms.mjs (ES module) → for import CMS from ‘@sveltia/cms’.
• outDir: package/dist

Custom Vite plugins:

• copyPackageFiles()
  • Reads root package.json.
  • Strips dev-only parts (dependencies, scripts).
  • Writes a trimmed package/package.json plus LICENSE.txt and README.md.
• generateExtraFiles()
  • generateTypes() → TypeScript declarations into package/.
  • generateSchema() → JSON schema into package/schema/sveltia-cms.json.

Result: pnpm build leaves a publishable package/ folder with:

• dist bundles (JS).
• main.d.ts + types/public.d.ts.
• schema/sveltia-cms.json.
• trimmed package.json, LICENSE, README.

🧬 Types and schema internals

Types:

• generateTypes() runs tsc on src/lib/main.js with allowJs and declarations only.
• Writes d.ts files (main.d.ts, types/public.d.ts).
• Appends a named export for CmsConfig.
• Normalizes deprecation markers inside public.d.ts.

Schema:

• generateSchema() uses ts-json-schema-generator on the CmsConfig type.
• Adds:
  • Title + description metadata.
  • $schema support at top of config files.
  • oneOf rule ensuring either collections or singletons is present.
  • widget name validation so custom widgets cannot collide with built-ins.
• Writes package/schema/sveltia-cms.json.
• Published at: https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

Usage in editors:

• In YAML config:

# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

• In TOML config:

#:schema https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json

• In JSON config:

"$schema": "https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json",

📂 Project layout (high level)

• src/lib/
  • main.js → library entry point (exports CMS API for embedding).
  • components/ → Svelte UI components for the CMS.
  • services/ → logic for contents, widgets, data output, backends, etc.
• package/
  • dist/ → build artifacts (JS bundles).
  • schema/ → sveltia-cms.json for config validation.
  • types/ → public TypeScript declarations.
  • main.d.ts → main type declarations.

(Exact module names may evolve, but this is the mental map.)

🐛 Dev & build gotchas

• Make sure Node version supports Vite 7 and Svelte 5 (current LTS is safe).
• Use pnpm consistently; mixing npm/yarn may leave conflicting lockfiles.
• If port 55151 is busy, Vite will fail (strictPort = true) instead of auto-switching; free the port or stop other dev servers.
• If build fails on types/schema, inspect scripts/generation and ts-json-schema-generator; type errors in CmsConfig ripple into schema generation.
• When publishing, prepublishOnly is wired to vite build; local publish tests should run pnpm build before npm publish / pnpm publish.