create-velocms-theme 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VeloCMS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# create-velocms-theme
+
+Scaffold a new VeloCMS theme project ready for npm publish.
+
+## Usage
+
+```bash
+npx create-velocms-theme my-theme
+```
+
+Or install globally:
+
+```bash
+npm install -g create-velocms-theme
+create-velocms-theme my-theme
+```
+
+## Prompts
+
+The CLI will ask you:
+
+1. **Theme name** — human-readable display name (e.g. "Minimal Portfolio")
+2. **Theme slug** — kebab-case package suffix (e.g. "minimal-portfolio")
+3. **Theme type** — `layout` | `niche` | `pack`
+4. **Niche category** — (only if type = niche) photographer | podcaster | restaurant | ...
+5. **Author name**
+6. **Author email**
+7. **License** — default: MIT
+8. **Short description**
+
+## Non-interactive mode
+
+```bash
+npx create-velocms-theme my-theme --non-interactive
+```
+
+Uses sensible defaults for CI environments.
+
+## Generated scaffold
+
+```
+my-theme/
+├── package.json           # velocms-theme-my-theme, peerDeps: react@19, next@16
+├── theme.manifest.json    # ThemeManifest (spec §4)
+├── tsconfig.json
+├── tsconfig.build.json
+├── README.md
+├── .gitignore
+├── preview/               # Place thumbnail.png + screenshots here
+└── src/
+    ├── index.ts           # Re-exports BlogIndex, PostLayout
+    ├── index.test.ts      # Smoke test (vitest) — extend as your theme grows
+    ├── BlogIndex.tsx      # Blog listing layout (TODO markers)
+    ├── PostLayout.tsx     # Single post layout (TODO markers)
+    ├── theme.config.ts    # Tailwind preset overrides
+    └── styles.css         # Global CSS tokens
+```
+
+## Building
+
+```bash
+npm run build   # compiles src/ → dist/
+```
+
+## Submitting to marketplace
+
+1. `npm run build`
+2. Verify `theme.manifest.json` is complete
+3. `npx velocms-cli theme submit` (coming Q3 2026)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { join } from "node:path";
+import { collectPrompts } from "./prompts.js";
+import { scaffoldTheme } from "./scaffold.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const nonInteractive = args.includes("--non-interactive");
+    const nameArg = args.find((a) => !a.startsWith("-"));
+    console.log("\nVeloCMS Theme Scaffolder\n");
+    let cfg;
+    try {
+        cfg = await collectPrompts(nameArg, nonInteractive);
+    }
+    catch (err) {
+        console.error("Failed to collect prompts:", err);
+        process.exit(1);
+    }
+    const outputDir = join(process.cwd(), cfg.slug);
+    console.log(`\nScaffolding theme "${cfg.name}" (${cfg.type}) into ./${cfg.slug}/`);
+    try {
+        scaffoldTheme(outputDir, cfg);
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            console.error(`Error: ${err.message}`);
+        }
+        else {
+            console.error("Unknown error:", err);
+        }
+        process.exit(1);
+    }
+    console.log(`\nDone! Theme scaffold created at ./${cfg.slug}/`);
+    console.log(`  cd ${cfg.slug}`);
+    console.log("  npm install");
+    console.log("  npm run dev");
+    console.log("\nWhen ready to submit:");
+    console.log("  npm run build");
+    console.log("  npx velocms-cli theme submit  (coming soon)\n");
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/prompts.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+export interface ThemeConfig {
+    name: string;
+    slug: string;
+    type: "layout" | "niche" | "pack";
+    authorName: string;
+    authorEmail: string;
+    license: string;
+    description: string;
+    niche?: string;
+}
+declare const VALID_TYPES: readonly ["layout", "niche", "pack"];
+declare const NICHE_CATEGORIES: readonly ["photographer", "podcaster", "restaurant", "creator", "writer", "agency", "developer", "indie-maker"];
+export type ThemeType = (typeof VALID_TYPES)[number];
+export type NicheCategory = (typeof NICHE_CATEGORIES)[number];
+export declare function collectPrompts(nameArg?: string, nonInteractive?: boolean): Promise<ThemeConfig>;
+export {};

package/dist/prompts.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline";
+const VALID_TYPES = ["layout", "niche", "pack"];
+const NICHE_CATEGORIES = [
+    "photographer",
+    "podcaster",
+    "restaurant",
+    "creator",
+    "writer",
+    "agency",
+    "developer",
+    "indie-maker",
+];
+function ask(question, defaultValue) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const query = defaultValue ? `${question} (${defaultValue}): ` : `${question}: `;
+        rl.question(query, (answer) => {
+            rl.close();
+            resolve(answer.trim() || defaultValue || "");
+        });
+    });
+}
+function toSlug(str) {
+    return str
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export async function collectPrompts(nameArg, nonInteractive = false) {
+    let name = nameArg ?? "";
+    if (!name && !nonInteractive) {
+        name = await ask("Theme name", "my-theme");
+    }
+    if (!name) {
+        name = "my-theme";
+    }
+    const defaultSlug = toSlug(name);
+    const slug = nonInteractive
+        ? defaultSlug
+        : await ask("Theme slug (kebab-case)", defaultSlug);
+    let type = "layout";
+    if (!nonInteractive) {
+        const typeAnswer = await ask("Theme type — layout | niche | pack", "layout");
+        if (VALID_TYPES.includes(typeAnswer)) {
+            type = typeAnswer;
+        }
+        else {
+            console.log(`Unknown type "${typeAnswer}", defaulting to "layout"`);
+        }
+    }
+    let niche;
+    if (type === "niche") {
+        if (!nonInteractive) {
+            const nicheAnswer = await ask(`Niche category — ${NICHE_CATEGORIES.join(" | ")}`, "photographer");
+            niche = nicheAnswer || "photographer";
+        }
+        else {
+            niche = "photographer";
+        }
+    }
+    const authorName = nonInteractive
+        ? "Theme Author"
+        : await ask("Author name", "Theme Author");
+    const authorEmail = nonInteractive
+        ? "author@example.com"
+        : await ask("Author email", "author@example.com");
+    const license = nonInteractive ? "MIT" : await ask("License", "MIT");
+    const description = nonInteractive
+        ? `A VeloCMS ${type} theme`
+        : await ask("Short description", `A VeloCMS ${type} theme`);
+    return { name, slug, type, authorName, authorEmail, license, description, niche };
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeConfig } from "./prompts.js";
+export declare function scaffoldTheme(outputDir: string, cfg: ThemeConfig): void;

package/dist/scaffold.js

@@ -0,0 +1,370 @@
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+function packageJsonContent(cfg) {
+    return JSON.stringify({
+        name: `velocms-theme-${cfg.slug}`,
+        version: "1.0.0",
+        description: cfg.description,
+        type: "module",
+        main: "./dist/index.js",
+        types: "./dist/index.d.ts",
+        scripts: {
+            build: "tsc -p tsconfig.build.json",
+            typecheck: "tsc --noEmit",
+            test: "vitest run",
+            dev: "tsc --watch",
+        },
+        keywords: ["velocms", "theme", cfg.type, ...(cfg.niche ? [cfg.niche] : [])],
+        author: {
+            name: cfg.authorName,
+            email: cfg.authorEmail,
+        },
+        license: cfg.license,
+        peerDependencies: {
+            react: "^19.0.0",
+            next: "^16.0.0",
+        },
+        devDependencies: {
+            typescript: "^5.0.0",
+            "@types/react": "^19.0.0",
+            vitest: "^4.0.0",
+        },
+        publishConfig: {
+            access: "public",
+        },
+    }, null, 2);
+}
+function manifestJsonContent(cfg) {
+    return JSON.stringify({
+        $schema: "https://velocms.org/schemas/theme-v1.json",
+        name: `velocms-theme-${cfg.slug}`,
+        displayName: cfg.name,
+        version: "1.0.0",
+        description: cfg.description,
+        author: {
+            name: cfg.authorName,
+            email: cfg.authorEmail,
+        },
+        type: cfg.type,
+        category: cfg.niche ?? "general",
+        tags: [cfg.type, ...(cfg.niche ? [cfg.niche] : [])],
+        engines: {
+            velocms: ">=1.0.0",
+        },
+        preview: {
+            thumbnail: "./preview/thumbnail.png",
+            screenshots: ["./preview/screenshot-1.png"],
+        },
+        exports: {
+            components: {
+                BlogLayout: "./dist/BlogIndex.js",
+                PostLayout: "./dist/PostLayout.js",
+                PageLayout: "./dist/PostLayout.js",
+            },
+        },
+        pricing: {
+            model: "free",
+        },
+    }, null, 2);
+}
+function tsconfigContent() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: "ES2020",
+            module: "ESNext",
+            moduleResolution: "bundler",
+            jsx: "react-jsx",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            outDir: "./dist",
+            rootDir: "./src",
+            declaration: true,
+            declarationDir: "./dist",
+        },
+        include: ["src"],
+        exclude: ["node_modules", "dist"],
+    }, null, 2);
+}
+function tsconfigBuildContent() {
+    return JSON.stringify({
+        extends: "./tsconfig.json",
+        compilerOptions: {
+            declaration: true,
+            sourceMap: false,
+            removeComments: true,
+        },
+        exclude: ["**/*.test.ts", "**/*.test.tsx"],
+    }, null, 2);
+}
+function indexTestTsContent(cfg) {
+    return `/**
+ * Smoke test for ${cfg.name} — verifies the theme entry point loads and
+ * exports the constants VeloCMS reads at install/registration time.
+ *
+ * Replace/extend with real component tests as your theme grows.
+ */
+
+import { describe, it, expect } from "vitest";
+import { THEME_SLUG, THEME_VERSION, BlogIndex, PostLayout } from "./index";
+
+describe("${cfg.name} theme entry point", () => {
+  it("exports the expected theme metadata", () => {
+    expect(THEME_SLUG).toBe("${cfg.slug}");
+    expect(THEME_VERSION).toBe("1.0.0");
+  });
+
+  it("exports BlogIndex and PostLayout components", () => {
+    expect(typeof BlogIndex).toBe("function");
+    expect(typeof PostLayout).toBe("function");
+  });
+});
+`;
+}
+function indexTsContent(cfg) {
+    const name = cfg.name;
+    const slug = cfg.slug;
+    return `/**
+ * ${name} — VeloCMS Theme
+ *
+ * Entry point. Re-exports all theme components.
+ * VeloCMS loads these via the manifest "exports.components" paths.
+ */
+
+export { BlogIndex } from "./BlogIndex";
+export { PostLayout } from "./PostLayout";
+
+// Theme metadata (convenience re-export for integrations)
+export const THEME_SLUG = "${slug}";
+export const THEME_VERSION = "1.0.0";
+`;
+}
+function blogIndexContent(cfg) {
+    return `/**
+ * BlogIndex — ${cfg.name}
+ *
+ * TODO: Replace with your actual blog listing layout.
+ * This minimal scaffold renders a list of post titles.
+ *
+ * Props injected by VeloCMS at render time:
+ * - posts: array of post objects
+ * - settings: tenant site settings
+ * - tenant: tenant context (id, slug, blogName, etc.)
+ */
+
+import React from "react";
+
+interface Post {
+  id: string;
+  title: string;
+  slug: string;
+  excerpt?: string;
+  published_at?: string;
+}
+
+interface BlogIndexProps {
+  posts: Post[];
+  settings?: { blog_name?: string; description?: string };
+  tenant?: { blogName?: string };
+}
+
+export function BlogIndex({ posts, settings, tenant }: BlogIndexProps) {
+  const blogName = tenant?.blogName ?? settings?.blog_name ?? "Blog";
+
+  return (
+    <main>
+      <header>
+        <h1>{blogName}</h1>
+        {settings?.description && <p>{settings.description}</p>}
+      </header>
+
+      {/* TODO: Add your custom layout, hero section, filter pills, etc. */}
+      <section>
+        {posts.map((post) => (
+          <article key={post.id}>
+            <h2>
+              <a href={\`/blog/\${post.slug}\`}>{post.title}</a>
+            </h2>
+            {post.excerpt && <p>{post.excerpt}</p>}
+          </article>
+        ))}
+      </section>
+    </main>
+  );
+}
+`;
+}
+function postLayoutContent(cfg) {
+    return `/**
+ * PostLayout — ${cfg.name}
+ *
+ * TODO: Replace with your actual single-post layout.
+ *
+ * Props injected by VeloCMS at render time:
+ * - post: the current post object
+ * - settings: tenant site settings
+ * - content: pre-rendered HTML string of the post body
+ */
+
+import React from "react";
+
+interface Post {
+  id: string;
+  title: string;
+  slug: string;
+  author_name?: string;
+  published_at?: string;
+  featured_image?: string;
+}
+
+interface PostLayoutProps {
+  post: Post;
+  content: string;
+  settings?: { blog_name?: string };
+}
+
+export function PostLayout({ post, content, settings }: PostLayoutProps) {
+  const blogName = settings?.blog_name ?? "Blog";
+
+  return (
+    <main>
+      <nav>
+        <a href="/blog">{blogName}</a>
+      </nav>
+
+      <article>
+        <header>
+          <h1>{post.title}</h1>
+          {post.author_name && (
+            <p>
+              By {post.author_name}
+              {post.published_at && (
+                <>
+                  {" · "}
+                  <time dateTime={post.published_at}>
+                    {new Date(post.published_at).toLocaleDateString()}
+                  </time>
+                </>
+              )}
+            </p>
+          )}
+        </header>
+
+        {/* TODO: Style the post body to match your theme */}
+        {/* eslint-disable-next-line react/no-danger */}
+        <div dangerouslySetInnerHTML={{ __html: content }} />
+      </article>
+    </main>
+  );
+}
+`;
+}
+function themeConfigContent(cfg) {
+    return `/**
+ * theme.config.ts — ${cfg.name}
+ *
+ * Tailwind CSS preset overrides applied when this theme is active.
+ * Extend the defaults object with your color palette, fonts, etc.
+ *
+ * See: https://tailwindcss.com/docs/configuration#presets
+ */
+
+const themeConfig = {
+  theme: {
+    extend: {
+      colors: {
+        // TODO: Add your palette
+        // primary: "oklch(60% 0.20 240)",
+      },
+      fontFamily: {
+        // TODO: Add your font stack
+        // sans: ["Inter", "ui-sans-serif", "system-ui"],
+      },
+    },
+  },
+};
+
+export default themeConfig;
+`;
+}
+function stylesCssContent(cfg) {
+    return `/**
+ * styles.css — ${cfg.name}
+ *
+ * Global CSS for this theme. Loaded alongside Tailwind utilities.
+ * Keep it minimal — prefer Tailwind classes in components.
+ *
+ * CSS custom properties prefixed with --theme- to avoid collisions.
+ */
+
+:root {
+  /* TODO: Replace with your theme tokens */
+  --theme-font-heading: system-ui, sans-serif;
+  --theme-font-body: system-ui, sans-serif;
+  --theme-color-bg: #ffffff;
+  --theme-color-text: #1a1a1a;
+  --theme-color-accent: oklch(60% 0.20 240);
+}
+
+/* TODO: Add your global base styles */
+`;
+}
+function readmeContent(cfg) {
+    return `# ${cfg.name}
+
+A VeloCMS ${cfg.type} theme${cfg.niche ? ` for ${cfg.niche}s` : ""}.
+
+## Getting started
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Build
+
+\`\`\`bash
+npm run build
+\`\`\`
+
+Produces \`dist/\` ready for publishing to the VeloCMS marketplace.
+
+## Publish to marketplace
+
+1. Build: \`npm run build\`
+2. Validate manifest: ensure \`theme.manifest.json\` is complete
+3. Submit: \`npx velocms-cli theme submit\` (coming soon)
+
+## License
+
+${cfg.license}
+`;
+}
+function gitignoreContent() {
+    return `node_modules/
+dist/
+*.tsbuildinfo
+.env
+.env.local
+`;
+}
+export function scaffoldTheme(outputDir, cfg) {
+    if (existsSync(outputDir)) {
+        throw new Error(`Directory already exists: ${outputDir}`);
+    }
+    mkdirSync(outputDir, { recursive: true });
+    mkdirSync(join(outputDir, "src"), { recursive: true });
+    mkdirSync(join(outputDir, "preview"), { recursive: true });
+    writeFileSync(join(outputDir, "package.json"), packageJsonContent(cfg));
+    writeFileSync(join(outputDir, "theme.manifest.json"), manifestJsonContent(cfg));
+    writeFileSync(join(outputDir, "tsconfig.json"), tsconfigContent());
+    writeFileSync(join(outputDir, "tsconfig.build.json"), tsconfigBuildContent());
+    writeFileSync(join(outputDir, "README.md"), readmeContent(cfg));
+    writeFileSync(join(outputDir, ".gitignore"), gitignoreContent());
+    writeFileSync(join(outputDir, "src", "index.ts"), indexTsContent(cfg));
+    writeFileSync(join(outputDir, "src", "index.test.ts"), indexTestTsContent(cfg));
+    writeFileSync(join(outputDir, "src", "BlogIndex.tsx"), blogIndexContent(cfg));
+    writeFileSync(join(outputDir, "src", "PostLayout.tsx"), postLayoutContent(cfg));
+    writeFileSync(join(outputDir, "src", "theme.config.ts"), themeConfigContent(cfg));
+    writeFileSync(join(outputDir, "src", "styles.css"), stylesCssContent(cfg));
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "create-velocms-theme",
+  "version": "1.0.0",
+  "description": "Scaffolding tool for VeloCMS theme development",
+  "type": "module",
+  "bin": {
+    "create-velocms-theme": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "dev": "node dist/index.js",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "keywords": [
+    "velocms",
+    "cms",
+    "theme",
+    "cli",
+    "scaffold",
+    "scaffolding",
+    "generator",
+    "create-velocms-theme"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "VeloCMS",
+    "url": "https://velocms.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VeloCMS/create-velocms-theme.git"
+  },
+  "homepage": "https://velocms.org/developers",
+  "bugs": {
+    "url": "https://github.com/VeloCMS/create-velocms-theme/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}