create-harper 1.8.1 → 1.9.0

package/lib/constants/frameworks.js

@@ -1,4 +1,5 @@
 import colors from 'picocolors';
+import { templates } from './templates.js';
 
 const {
 	blue,
@@ -22,80 +23,47 @@ const {
  * @property {Variant[]} variants - The available variants for this framework.
  */
 
+/** Display name and color for each framework family. */
+const frameworkMeta = {
+	vanilla: { display: 'Vanilla', color: yellow },
+	react: { display: 'React', color: cyan },
+	vue: { display: 'Vue', color: green },
+};
+
 /**
- * The list of supported frameworks and their variants.
+ * The list of supported frameworks and their variants, derived from the template catalog so the
+ * interactive picker stays in sync with the single source of truth.
  * @type {Framework[]}
  */
-export const frameworks = [
-	{
-		name: 'vanilla',
-		display: 'Vanilla',
-		color: yellow,
-		variants: [
-			{
-				name: 'vanilla-ts',
-				display: 'TypeScript',
-				color: blue,
-			},
-			{
-				name: 'vanilla',
-				display: 'JavaScript',
-				color: yellow,
-			},
-		],
-	},
-	{
-		name: 'react',
-		display: 'React',
-		color: cyan,
-		variants: [
-			{
-				name: 'react-ts',
-				display: 'TypeScript',
-				color: blue,
-			},
-			{
-				name: 'react',
-				display: 'JavaScript',
-				color: yellow,
-			},
-			{
-				name: 'react-ts-ssr',
-				display: 'TypeScript + SSR',
-				color: blue,
-			},
-			{
-				name: 'react-ssr',
-				display: 'JavaScript + SSR',
-				color: yellow,
-			},
-		],
-	},
-	{
-		name: 'vue',
-		display: 'Vue',
-		color: green,
-		variants: [
-			{
-				name: 'vue-ts',
-				display: 'TypeScript',
-				color: blue,
-			},
-			{
-				name: 'vue',
-				display: 'JavaScript',
-				color: yellow,
-			},
-			{
-				name: 'vue-ts-ssr',
-				display: 'TypeScript + SSR',
-				color: blue,
-			},
-			{
-				name: 'vue-ssr',
-				display: 'JavaScript + SSR',
-				color: yellow,
-			},
-		],
-	},
-];
+export const frameworks = (() => {
+	/** @type {Framework[]} */
+	const grouped = [];
+	const byName = new Map();
+
+	for (const t of templates) {
+		let framework = byName.get(t.framework);
+		if (!framework) {
+			const meta = frameworkMeta[t.framework];
+			if (!meta) {
+				throw new Error(
+					`Missing framework metadata for "${t.framework}". Please add it to frameworkMeta in frameworks.js.`,
+				);
+			}
+			framework = {
+				name: t.framework,
+				display: meta.display,
+				color: meta.color,
+				variants: [],
+			};
+			byName.set(t.framework, framework);
+			grouped.push(framework);
+		}
+		framework.variants.push({
+			name: t.name,
+			display: `${t.typescript ? 'TypeScript' : 'JavaScript'}${t.ssr ? ' + SSR' : ''}`,
+			color: t.typescript ? blue : yellow,
+		});
+	}
+
+	return grouped;
+})();

package/lib/constants/helpMessage.js

@@ -1,10 +1,19 @@
-import colors from 'picocolors';
+import { frameworks } from './frameworks.js';
 
-const {
-	cyan,
-	green,
-	yellow,
-} = colors;
+/** Width of each template-name column in the "Available templates" list. */
+const COLUMN_WIDTH = 20;
+
+/**
+ * One color-coded line per framework, listing its variants in aligned columns. Derived from the
+ * template catalog (via {@link frameworks}) so new templates appear in `--help` automatically.
+ */
+const availableTemplates = frameworks
+	.map((framework) =>
+		framework.color(
+			framework.variants.map((variant) => variant.name.padEnd(COLUMN_WIDTH)).join('').trimEnd(),
+		)
+	)
+	.join('\n');
 
 /**
  * The help message displayed when using the --help flag or on invalid input.
@@ -30,6 +39,4 @@ If you are going to deploy your application to https://fabric.harper.fast/, you
                                         For authentication, use "harper login" in your project directory.
 
 Available templates:
-${yellow('vanilla-ts          vanilla')}
-${cyan('react-ts            react               react-ts-ssr        react-ssr')}
-${green('vue-ts              vue                 vue-ts-ssr          vue-ssr')}`;
+${availableTemplates}`;

package/lib/constants/templates.d.ts

@@ -0,0 +1,54 @@
+export type Framework = 'vanilla' | 'react' | 'vue';
+
+export type TemplateName =
+	| 'vanilla-ts'
+	| 'vanilla'
+	| 'react-ts'
+	| 'react'
+	| 'react-ts-ssr'
+	| 'react-ssr'
+	| 'vue-ts'
+	| 'vue'
+	| 'vue-ts-ssr'
+	| 'vue-ssr';
+
+export interface TemplateInfo {
+	/** The canonical template name (e.g. 'vanilla', 'react-ts'). Used to scaffold. */
+	name: TemplateName;
+	/** The framework family this template belongs to. */
+	framework: Framework;
+	/** A human-friendly display title. */
+	title: string;
+	/** A short description of the template. */
+	description: string;
+	/** Tags describing the template's stack. */
+	tags: string[];
+	/** Whether the template uses TypeScript. */
+	typescript: boolean;
+	/** Whether the template is server-side rendered. */
+	ssr: boolean;
+	/** The published Studio template package for this template. */
+	npmPackage: string;
+	/** A link to the template's source on GitHub. */
+	githubUrl: string;
+}
+
+/** The catalog of every template create-harper can scaffold, in display order. */
+export declare const templates: readonly TemplateInfo[];
+
+/**
+ * The flat list of every template name, in catalog order, typed as a non-empty tuple of string
+ * literals so it can be passed straight to `z.enum(...)` and yield a literal union.
+ */
+export declare const templateNames: readonly [
+	'vanilla-ts',
+	'vanilla',
+	'react-ts',
+	'react',
+	'react-ts-ssr',
+	'react-ssr',
+	'vue-ts',
+	'vue',
+	'vue-ts-ssr',
+	'vue-ssr',
+];

package/lib/constants/templates.js

@@ -1,10 +1,142 @@
-import { frameworks } from './frameworks.js';
+const CREATE_HARPER_TREE = 'https://github.com/HarperFast/create-harper/tree/main';
 
 /**
- * A list of all available template names derived from the frameworks and their variants.
+ * @typedef {'vanilla' | 'react' | 'vue'} Framework
+ */
+
+/**
+ * @typedef {Object} TemplateInfo
+ * @property {string} name - The canonical template name (e.g. 'vanilla', 'react-ts'). Used to scaffold.
+ * @property {Framework} framework - The framework family this template belongs to.
+ * @property {string} title - A human-friendly display title.
+ * @property {string} description - A short description of the template.
+ * @property {string[]} tags - Tags describing the template's stack.
+ * @property {boolean} typescript - Whether the template uses TypeScript.
+ * @property {boolean} ssr - Whether the template is server-side rendered.
+ * @property {string} npmPackage - The published Studio template package for this template.
+ * @property {string} githubUrl - A link to the template's source on GitHub.
+ */
+
+/**
+ * Build a {@link TemplateInfo} entry, deriving the npm package and GitHub URL from the template name.
+ *
+ * @param {Omit<TemplateInfo, 'npmPackage' | 'githubUrl'>} info
+ * @returns {TemplateInfo}
+ */
+function template(info) {
+	return {
+		...info,
+		npmPackage: `@harperfast/template-${info.name}-studio`,
+		githubUrl: `${CREATE_HARPER_TREE}/template-${info.name}`,
+	};
+}
+
+/**
+ * The catalog of every template create-harper can scaffold. This is the single source of truth from
+ * which {@link templateNames} (the flat name list) and
+ * {@link import('./frameworks.js').frameworks} (the interactive picker) are derived.
+ *
+ * Order is significant: it determines the order of the flat name list and the CLI picker.
+ *
+ * @type {TemplateInfo[]}
+ */
+export const templates = [
+	template({
+		name: 'vanilla-ts',
+		framework: 'vanilla',
+		title: 'Vanilla + TypeScript',
+		description: 'The same Web + REST ORM from the first template, but with TypeScript sprinkled in.',
+		tags: ['Vanilla', 'TypeScript', 'GraphQL'],
+		typescript: true,
+		ssr: false,
+	}),
+	template({
+		name: 'vanilla',
+		framework: 'vanilla',
+		title: 'Vanilla JS',
+		description: "Define your entities in schema.graphql, add your HTML/CSS/JS in web, and you're cooking!",
+		tags: ['Vanilla', 'REST', 'GraphQL', 'ORM'],
+		typescript: false,
+		ssr: false,
+	}),
+	template({
+		name: 'react-ts',
+		framework: 'react',
+		title: 'React + TypeScript',
+		description: 'The same Vite-powered React app, with end-to-end type safety from TypeScript.',
+		tags: ['React', 'TypeScript', 'Vite', 'SPA'],
+		typescript: true,
+		ssr: false,
+	}),
+	template({
+		name: 'react',
+		framework: 'react',
+		title: 'React',
+		description: "A Vite-powered React single-page app, wired up to Harper's REST + GraphQL APIs out of the box.",
+		tags: ['React', 'Vite', 'SPA', 'GraphQL'],
+		typescript: false,
+		ssr: false,
+	}),
+	template({
+		name: 'react-ts-ssr',
+		framework: 'react',
+		title: 'React + TypeScript + SSR',
+		description: 'Server-rendered React with Vite and TypeScript for type-safe, SEO-friendly pages on Harper.',
+		tags: ['React', 'TypeScript', 'SSR', 'Vite'],
+		typescript: true,
+		ssr: true,
+	}),
+	template({
+		name: 'react-ssr',
+		framework: 'react',
+		title: 'React + SSR',
+		description: 'Server-rendered React with Vite for fast first paints, hydrating into a full SPA on Harper.',
+		tags: ['React', 'SSR', 'Vite', 'GraphQL'],
+		typescript: false,
+		ssr: true,
+	}),
+	template({
+		name: 'vue-ts',
+		framework: 'vue',
+		title: 'Vue + TypeScript',
+		description: 'The same Vite-powered Vue app, with end-to-end type safety from TypeScript.',
+		tags: ['Vue', 'TypeScript', 'Vite', 'SPA'],
+		typescript: true,
+		ssr: false,
+	}),
+	template({
+		name: 'vue',
+		framework: 'vue',
+		title: 'Vue',
+		description: "A Vite-powered Vue single-page app, wired up to Harper's REST + GraphQL APIs out of the box.",
+		tags: ['Vue', 'Vite', 'SPA', 'GraphQL'],
+		typescript: false,
+		ssr: false,
+	}),
+	template({
+		name: 'vue-ts-ssr',
+		framework: 'vue',
+		title: 'Vue + TypeScript + SSR',
+		description: 'Server-rendered Vue with Vite and TypeScript for type-safe, SEO-friendly pages on Harper.',
+		tags: ['Vue', 'TypeScript', 'SSR', 'Vite'],
+		typescript: true,
+		ssr: true,
+	}),
+	template({
+		name: 'vue-ssr',
+		framework: 'vue',
+		title: 'Vue + SSR',
+		description: 'Server-rendered Vue with Vite for fast first paints, hydrating into a full SPA on Harper.',
+		tags: ['Vue', 'SSR', 'Vite', 'GraphQL'],
+		typescript: false,
+		ssr: true,
+	}),
+];
+
+/**
+ * The flat list of every template name, in catalog order. This is the canonical, dependency-free list
+ * other tools can import to validate or enumerate templates.
+ *
  * @type {string[]}
  */
-export const templates = frameworks.map((f) => f.variants.map((v) => v.name)).reduce(
-	(a, b) => a.concat(b),
-	[],
-);
+export const templateNames = templates.map((t) => t.name);

package/lib/steps/getTemplate.js

@@ -1,6 +1,6 @@
 import * as prompts from '@clack/prompts';
 import { frameworks } from '../constants/frameworks.js';
-import { templates } from '../constants/templates.js';
+import { templateNames } from '../constants/templates.js';
 
 /**
  * Step 4: Choose a project template (framework and variant).
@@ -13,7 +13,7 @@ export async function getTemplate(argTemplate, interactive) {
 	let template = argTemplate;
 	let hasInvalidArgTemplate = false;
 
-	if (argTemplate && !templates.includes(argTemplate)) {
+	if (argTemplate && !templateNames.includes(argTemplate)) {
 		template = undefined;
 		hasInvalidArgTemplate = true;
 	}

package/package.json

@@ -1,8 +1,15 @@
 {
 	"name": "create-harper",
 	"description": "Scaffold a new Harper project in JavaScript or TypeScript.",
-	"version": "1.8.1",
+	"version": "1.9.0",
 	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		"./templates": {
+			"types": "./lib/constants/templates.d.ts",
+			"import": "./lib/constants/templates.js"
+		}
+	},
 	"author": {
 		"name": "HarperDB",
 		"email": "support@harperdb.io"