create-hsi-app 0.5.2 → 0.6.0

package/README.md

@@ -1,6 +1,7 @@
 # create-hsi-app
 
-Scaffold a new Vite + React + TypeScript app from the frontend template.
+Scaffold a new Vite or Next.js + React + TypeScript app from the frontend
+template.
 
 ## Usage
 
@@ -29,4 +30,4 @@ bun create hsi-app@latest
 ```
 
 Full CLI usage, flags, and repo/install behavior:
-[docs/create-hsi-app.md](https://github.com/Hsiii/frontend-template/blob/main/docs/create-hsi-app.md)
+[docs/CLI.md](https://github.com/Hsiii/frontend-template/blob/main/docs/CLI.md)

package/bin/create-hsi-app.mjs

@@ -2,27 +2,41 @@
 import { execFileSync } from 'node:child_process';
 import {
     existsSync,
+    mkdirSync,
     readdirSync,
     readFileSync,
     rmSync,
     writeFileSync,
 } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { stdin as input, stdout as output } from 'node:process';
-import readline from 'node:readline/promises';
+
+import {
+    closePrompts,
+    confirm,
+    fail,
+    gap,
+    intro,
+    ready,
+    section,
+    select,
+    text,
+    warn,
+} from './ui.mjs';
 
 const templateRepo = 'https://github.com/Hsiii/frontend-template.git';
-const templateTag = 'v0.5.2';
+const templateTag = 'v0.6.0';
 const defaultAppName = 'my-app';
 const packageManagers = ['bun', 'npm', 'pnpm', 'yarn'];
+const nextVersion = '16.2.7';
 const rawArgs = process.argv.slice(2);
 const parsedArgs = parseCliArgs(rawArgs);
 const selectedPackageManager = resolvePackageManager(parsedArgs);
-const shouldInstallDependencies = !(
+let selectedFramework = resolveFramework(parsedArgs);
+let shouldInstallDependencies = !(
     parsedArgs.noInstall || readNpmBooleanFlag('noinstall')
 );
 const shouldSkipRepoSetup = parsedArgs.noRepo || readNpmBooleanFlag('norepo');
-const isInteractive = input.isTTY && output.isTTY;
+const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
 const targetArg = parsedArgs.targetArg ?? '.';
 const targetPath = resolve(targetArg);
 const appName = toPackageName(basename(targetPath));
@@ -36,6 +50,13 @@ async function main() {
         fail(`Target directory is not empty: ${targetPath}`);
     }
 
+    intro(appName, targetPath);
+    selectedFramework = await planFramework();
+    const repoPlan = await planRepoSetup();
+    shouldInstallDependencies = await planInstallDependencies();
+    closePrompts();
+
+    section(`Cloning ${frameworkLabel(selectedFramework)} template`);
     run('git', [
         '-c',
         'advice.detachedHead=false',
@@ -56,35 +77,30 @@ async function main() {
 
     updatePackageJson();
     updateBunLock();
+    console.log();
+    section('Customizing project files');
+    console.log(`- framework: ${frameworkLabel(selectedFramework)}`);
+    console.log(`- package.json: name, version, scripts, packageManager`);
+    logFrameworkFileChanges();
+    console.log(`- README.md: install/dev/check commands`);
+    console.log(`- package manager config: ${packageManagerConfigFile()}`);
+    if (selectedPackageManager === 'bun') {
+        console.log(`- bun.lock: package name`);
+    }
+    updateFrameworkFiles();
     updateAppText();
     updatePackageManagerFiles();
     writeAppReadme();
 
     if (shouldInstallDependencies) {
+        console.log();
+        section(`Installing dependencies with ${selectedPackageManager}`);
         installDependencies();
     }
 
-    const repoSetup = await maybeSetupRepo();
+    await applyRepoPlan(repoPlan);
 
-    console.log(`\nCreated ${appName} in ${targetPath}\n`);
-    if (repoSetup === 'github') {
-        console.log(
-            'Created a local git repository and configured GitHub origin.'
-        );
-    } else if (repoSetup === 'local') {
-        console.log('Initialized a local git repository.');
-    }
-    if (shouldInstallDependencies) {
-        console.log(`Installed dependencies with ${selectedPackageManager}.`);
-    }
-    console.log('\nNext steps:');
-    if (targetArg !== '.') {
-        console.log(`  cd ${targetArg}`);
-    }
-    if (!shouldInstallDependencies) {
-        console.log(`  ${installCommand()}`);
-    }
-    console.log(`  ${devCommand()}`);
+    ready(appName, nextSteps());
 }
 
 function run(command, args, options = {}) {
@@ -116,8 +132,20 @@ function updatePackageJson() {
     delete packageJson.engines;
     delete packageJson.scripts.prepare;
     delete packageJson.scripts.release;
-    packageJson.scripts.check =
-        'tsc -p tsconfig.json --noEmit && eslint . && prettier . --check && vite build';
+    if (selectedFramework === 'next') {
+        packageJson.scripts.dev = 'next dev';
+        packageJson.scripts.build = 'next build';
+        packageJson.scripts.preview = 'next start';
+        packageJson.scripts.check =
+            'tsc -p tsconfig.json --noEmit && eslint . && prettier . --check && next build';
+        packageJson.dependencies.next = nextVersion;
+        packageJson.devDependencies['@next/eslint-plugin-next'] = nextVersion;
+        delete packageJson.devDependencies['@vitejs/plugin-react'];
+        delete packageJson.devDependencies.vite;
+    } else {
+        packageJson.scripts.check =
+            'tsc -p tsconfig.json --noEmit && eslint . && prettier . --check && vite build';
+    }
     packageJson.packageManager = packageManagerDeclaration();
 
     writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 4)}\n`);
@@ -144,20 +172,23 @@ function updateBunLock() {
 }
 
 function updateAppText() {
-    replaceInFile(
-        join(targetPath, 'index.html'),
-        '<title>Frontend Template</title>',
-        {
-            with: `<title>${appName}</title>`,
-        }
-    );
-    replaceInFile(
-        join(targetPath, 'src/components/App.tsx'),
-        '>Frontend Template<',
-        {
-            with: `>${appName}<`,
-        }
-    );
+    if (selectedFramework === 'vite') {
+        replaceInFile(
+            join(targetPath, 'index.html'),
+            '<title>Frontend Template</title>',
+            {
+                with: `<title>${appName}</title>`,
+            }
+        );
+    }
+
+    writeFileSync(join(targetPath, 'src/components/App.tsx'), appComponent());
+}
+
+function updateFrameworkFiles() {
+    if (selectedFramework === 'next') {
+        writeNextAppFiles();
+    }
 }
 
 function updatePackageManagerFiles() {
@@ -219,7 +250,7 @@ function writeAppReadme() {
     const securityNote = securityNoteForPackageManager();
     const readme = `# ${appName}
 
-Created from the frontend template.
+Created from the ${frameworkLabel(selectedFramework)} frontend template.
 
 ## Install
 
@@ -245,58 +276,132 @@ ${securityNote}
     writeFileSync(join(targetPath, 'README.md'), readme);
 }
 
-async function maybeSetupRepo() {
+async function planFramework() {
+    if (parsedArgs.framework || !isInteractive) {
+        return selectedFramework;
+    }
+
+    const framework = await select({
+        message: 'Framework',
+        options: [
+            { label: 'Vite', value: 'vite' },
+            { label: 'Next.js', value: 'next' },
+        ],
+        initialValue: 'vite',
+    });
+    gap();
+
+    return framework;
+}
+
+async function planInstallDependencies() {
+    if (!shouldInstallDependencies || !isInteractive) {
+        return shouldInstallDependencies;
+    }
+
+    const shouldInstall = await confirm({
+        message: `Should I run "${installCommand()}" for you?`,
+        initialValue: true,
+    });
+    gap();
+
+    return shouldInstall;
+}
+
+async function planRepoSetup() {
     if (shouldSkipRepoSetup || !isInteractive) {
         return null;
     }
 
-    const rl = readline.createInterface({ input, output });
+    const shouldCreateRepo = await confirm({
+        message: 'Create a git repository?',
+        initialValue: true,
+    });
+    gap();
 
-    try {
-        const shouldCreateRepo = await promptYesNo(
-            rl,
-            'Create a git repository?',
-            true
+    if (!shouldCreateRepo) {
+        return null;
+    }
+
+    const repoPlan = {
+        git: true,
+        github: false,
+    };
+    const hasGitHubCli = canUseGitHubCli();
+
+    if (!hasGitHubCli) {
+        warn(
+            'GitHub CLI is unavailable or not authenticated; keeping a local repository only.'
         );
+        gap();
+        return repoPlan;
+    }
 
-        if (!shouldCreateRepo) {
-            return null;
-        }
+    const shouldCreateGitHubRepo = await confirm({
+        message: 'Create a GitHub repository too?',
+        initialValue: true,
+    });
+    gap();
+
+    if (!shouldCreateGitHubRepo) {
+        return repoPlan;
+    }
 
-        initLocalRepo();
+    const defaultRepoName = basename(targetPath);
+    const repoName = await text({
+        message: 'Repository name',
+        defaultValue: defaultRepoName,
+        placeholder: defaultRepoName,
+        validate(value) {
+            return value.trim() ? undefined : 'Repository name is required.';
+        },
+    });
+    gap();
+    const visibility = await select({
+        message: 'Visibility',
+        options: [
+            { label: 'Private', value: 'private' },
+            { label: 'Public', value: 'public' },
+        ],
+        initialValue: 'private',
+    });
+    gap();
+
+    return {
+        ...repoPlan,
+        github: true,
+        repoName,
+        visibility,
+    };
+}
 
-        if (!canUseGitHubCli()) {
-            return 'local';
-        }
+async function applyRepoPlan(repoPlan) {
+    if (!repoPlan) {
+        return;
+    }
 
-        const defaultRepoName = basename(targetPath);
-        const repoName = await promptWithDefault(
-            rl,
-            'Repository name',
-            defaultRepoName
-        );
-        const visibility = await promptChoice(rl, 'Visibility', [
-            { label: 'private', value: 'private', default: true },
-            { label: 'public', value: 'public' },
-        ]);
-
-        run(
-            'gh',
-            [
-                'repo',
-                'create',
-                repoName,
-                `--${visibility}`,
-                '--source=.',
-                '--remote=origin',
-            ],
-            { cwd: targetPath }
-        );
+    console.log();
+    section('Initializing local git repository');
+    initLocalRepo();
 
-        return 'github';
-    } finally {
-        rl.close();
+    if (!repoPlan.github) {
+        return;
     }
+
+    console.log();
+    section('Creating GitHub repository');
+    run(
+        'gh',
+        [
+            'repo',
+            'create',
+            repoPlan.repoName,
+            `--${repoPlan.visibility}`,
+            '--source=.',
+            '--remote=origin',
+        ],
+        { cwd: targetPath }
+    );
 }
 
 function initLocalRepo() {
@@ -305,71 +410,29 @@ function initLocalRepo() {
 }
 
 function canUseGitHubCli() {
-    return Boolean(
+    return (
         run('gh', ['auth', 'status'], {
             cwd: targetPath,
             capture: true,
             allowFailure: true,
-        })
+        }) !== null
     );
 }
 
-async function promptYesNo(rl, label, defaultValue) {
-    const hint = defaultValue ? 'Y/n' : 'y/N';
-
-    while (true) {
-        const answer = (await rl.question(`${label} [${hint}] `))
-            .trim()
-            .toLowerCase();
-
-        if (!answer) {
-            return defaultValue;
-        }
-
-        if (['y', 'yes'].includes(answer)) {
-            return true;
-        }
+function nextSteps() {
+    const steps = [];
 
-        if (['n', 'no'].includes(answer)) {
-            return false;
-        }
+    if (targetArg !== '.') {
+        steps.push(`cd ${targetArg}`);
     }
-}
-
-async function promptWithDefault(rl, label, defaultValue) {
-    const answer = (await rl.question(`${label} (${defaultValue}): `)).trim();
-
-    return answer || defaultValue;
-}
-
-async function promptChoice(rl, label, choices) {
-    const renderedChoices = choices
-        .map((choice) =>
-            choice.default ? `${choice.label.toUpperCase()}` : choice.label
-        )
-        .join('/');
-
-    while (true) {
-        const answer = (await rl.question(`${label} (${renderedChoices}): `))
-            .trim()
-            .toLowerCase();
 
-        if (!answer) {
-            const defaultChoice = choices.find((choice) => choice.default);
-
-            if (defaultChoice) {
-                return defaultChoice.value;
-            }
-        }
+    if (!shouldInstallDependencies) {
+        steps.push(installCommand());
+    }
 
-        const matchingChoice = choices.find(
-            (choice) => choice.label === answer || choice.value === answer
-        );
+    steps.push(devCommand());
 
-        if (matchingChoice) {
-            return matchingChoice.value;
-        }
-    }
+    return steps;
 }
 
 function replaceInFile(filePath, searchValue, replacement) {
@@ -391,6 +454,7 @@ function toPackageName(value) {
 
 function parseCliArgs(args) {
     const parsedArgs = {
+        framework: null,
         noInstall: false,
         noRepo: false,
         packageManager: null,
@@ -399,6 +463,12 @@ function parseCliArgs(args) {
 
     for (const arg of args) {
         switch (arg) {
+            case '--vite':
+                setFrameworkOverride(parsedArgs, 'vite');
+                continue;
+            case '--next':
+                setFrameworkOverride(parsedArgs, 'next');
+                continue;
             case '--bun':
                 setPackageManagerOverride(parsedArgs, 'bun');
                 continue;
@@ -433,6 +503,14 @@ function parseCliArgs(args) {
     return parsedArgs;
 }
 
+function setFrameworkOverride(parsedArgs, framework) {
+    if (parsedArgs.framework && parsedArgs.framework !== framework) {
+        fail('Pass only one of --vite or --next.');
+    }
+
+    parsedArgs.framework = framework;
+}
+
 function setPackageManagerOverride(parsedArgs, packageManager) {
     if (
         parsedArgs.packageManager &&
@@ -448,12 +526,295 @@ function resolvePackageManager(parsedArgs) {
     return parsedArgs.packageManager ?? 'bun';
 }
 
+function resolveFramework(parsedArgs) {
+    return parsedArgs.framework ?? 'vite';
+}
+
 function readNpmBooleanFlag(name) {
     const value = process.env[`npm_config_${name}`];
 
     return value === 'true' || value === '';
 }
 
+function logFrameworkFileChanges() {
+    if (selectedFramework === 'next') {
+        console.log(
+            `- Next app router files: src/app/layout.tsx, src/app/page.tsx`
+        );
+        console.log(`- src/app/global.css: app styles`);
+        console.log(`- Next config: next.config.mjs, next-env.d.ts`);
+        console.log(
+            `- Vite files removed: index.html, vite.config.mjs, src/main.tsx`
+        );
+        return;
+    }
+
+    console.log(`- index.html: title`);
+    console.log(`- src/components/App.tsx: app name`);
+}
+
+function writeNextAppFiles() {
+    rmSync(join(targetPath, 'index.html'), { force: true });
+    rmSync(join(targetPath, 'vite.config.mjs'), { force: true });
+    rmSync(join(targetPath, 'src/main.tsx'), { force: true });
+    rmSync(join(targetPath, 'src/vite-env.d.ts'), { force: true });
+    rmSync(join(targetPath, 'src/global.css'), { force: true });
+
+    const appPath = join(targetPath, 'src/app');
+    mkdirSync(appPath, { recursive: true });
+
+    writeFileSync(join(targetPath, 'next-env.d.ts'), nextEnvTypes());
+    writeFileSync(join(targetPath, 'next.config.mjs'), nextConfig());
+    writeFileSync(join(targetPath, 'eslint.config.mjs'), nextEslintConfig());
+    writeFileSync(join(targetPath, 'tsconfig.json'), nextTsconfig());
+    writeFileSync(join(appPath, 'layout.tsx'), nextLayout());
+    writeFileSync(join(appPath, 'page.tsx'), nextPage());
+    writeFileSync(join(appPath, 'global.css'), nextGlobalCss());
+}
+
+function frameworkLabel(framework) {
+    switch (framework) {
+        case 'vite':
+            return 'Vite';
+        case 'next':
+            return 'Next.js';
+        default:
+            fail(`Unsupported framework: ${framework}`);
+    }
+}
+
+function frameworkTitle(framework) {
+    switch (framework) {
+        case 'vite':
+            return 'Vite, React, and TypeScript.';
+        case 'next':
+            return 'Next.js, React, and TypeScript.';
+        default:
+            fail(`Unsupported framework: ${framework}`);
+    }
+}
+
+function appComponent() {
+    return `import type { JSX } from 'react';
+
+export function App(): JSX.Element {
+    return (
+        <main className='app'>
+            <section className='app__content'>
+                <p className='app__eyebrow'>${appName}</p>
+                <h1 className='app__title'>${frameworkTitle(selectedFramework)}</h1>
+                <p className='app__description'>
+                    A clean baseline with strict tooling, useful tokens, and no
+                    unnecessary UI noise.
+                </p>
+            </section>
+        </main>
+    );
+}
+`;
+}
+
+function nextEnvTypes() {
+    return `/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// This file should not be edited.
+`;
+}
+
+function nextConfig() {
+    return `/** @type {import("next").NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;
+`;
+}
+
+function nextEslintConfig() {
+    return `import nextPlugin from '@next/eslint-plugin-next';
+import { completeConfigBase } from 'eslint-config-complete';
+
+export default [
+    ...completeConfigBase,
+
+    {
+        ignores: ['.next/**', 'node_modules/**'],
+    },
+
+    {
+        plugins: {
+            '@next/next': nextPlugin,
+        },
+        rules: {
+            ...nextPlugin.configs.recommended.rules,
+            ...nextPlugin.configs['core-web-vitals'].rules,
+            '@stylistic/quotes': [
+                'error',
+                'single',
+                {
+                    avoidEscape: true,
+                },
+            ],
+            'import-x/no-unassigned-import': [
+                'error',
+                {
+                    allow: ['**/*.css'],
+                },
+            ],
+        },
+    },
+
+    {
+        files: ['src/app/**/*.tsx'],
+        rules: {
+            'import-x/no-default-export': 'off',
+        },
+    },
+];
+`;
+}
+
+function nextTsconfig() {
+    return `{
+    "compilerOptions": {
+        "target": "ES2022",
+        "lib": ["DOM", "DOM.Iterable", "ES2022"],
+        "allowJs": false,
+        "skipLibCheck": true,
+        "strict": true,
+        "noEmit": true,
+        "esModuleInterop": true,
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "jsx": "react-jsx",
+        "incremental": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true,
+        "plugins": [
+            {
+                "name": "next"
+            }
+        ],
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    },
+    "include": [
+        "next-env.d.ts",
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        ".next/dev/types/**/*.ts",
+        ".next/types/**/*.ts"
+    ],
+    "exclude": ["node_modules"]
+}
+`;
+}
+
+function nextLayout() {
+    return `import type { JSX, ReactNode } from 'react';
+import type { Metadata } from 'next';
+
+import './global.css';
+
+export const metadata: Metadata = {
+    title: '${appName}',
+    description: 'Created from create-hsi-app.',
+};
+
+interface RootLayoutProps {
+    readonly children: ReactNode;
+}
+
+export default function RootLayout({ children }: RootLayoutProps): JSX.Element {
+    return (
+        <html lang='en'>
+            <body>{children}</body>
+        </html>
+    );
+}
+`;
+}
+
+function nextPage() {
+    return `import type { JSX } from 'react';
+
+import { App } from '@/components/App';
+
+export default function HomePage(): JSX.Element {
+    return <App />;
+}
+`;
+}
+
+function nextGlobalCss() {
+    return `@import '../constants/color.css';
+@import '../constants/font.css';
+
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+html {
+    background-color: var(--clr-bg);
+    color: var(--clr-text);
+}
+
+body {
+    min-width: 320px;
+    min-height: 100vh;
+    font: var(--font-body-md);
+    line-height: 1.5;
+    background-color: var(--clr-bg);
+}
+
+a {
+    color: inherit;
+}
+
+:focus-visible {
+    outline: calc(var(--space-16) / 8) solid var(--clr-accent);
+    outline-offset: calc(var(--space-16) / 8);
+}
+
+.app {
+    min-height: 100vh;
+    display: grid;
+    place-items: center;
+    padding: var(--space-32) var(--space-24);
+}
+
+.app__content {
+    display: grid;
+    justify-items: center;
+    gap: var(--space-16);
+    width: fit-content;
+    max-width: 100%;
+    text-align: center;
+}
+
+.app__eyebrow {
+    color: var(--clr-text-muted);
+    font: var(--font-label);
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+}
+
+.app__title {
+    font: var(--font-display);
+}
+
+.app__description {
+    color: var(--clr-text-muted);
+}
+`;
+}
+
 function packageManagerDeclaration() {
     switch (selectedPackageManager) {
         case 'bun':
@@ -525,7 +886,17 @@ function securityNoteForPackageManager() {
     }
 }
 
-function fail(message) {
-    console.error(`create-hsi-app: ${message}`);
-    process.exit(1);
+function packageManagerConfigFile() {
+    switch (selectedPackageManager) {
+        case 'bun':
+            return 'bunfig.toml';
+        case 'npm':
+            return '.npmrc';
+        case 'pnpm':
+            return 'pnpm-workspace.yaml';
+        case 'yarn':
+            return '.yarnrc.yml';
+        default:
+            fail(`Unsupported package manager: ${selectedPackageManager}`);
+    }
 }

package/bin/ui.mjs

@@ -0,0 +1,70 @@
+import * as prompts from '@clack/prompts';
+import color from 'picocolors';
+
+const branch = color.dim('│');
+
+export function intro(appName, targetPath) {
+    prompts.intro(color.inverse(' create-hsi-app '));
+    console.log(branch);
+    console.log(
+        `${color.cyan('◇')}  Scaffolding ${color.bold(appName)} in ${targetPath}`
+    );
+    console.log(branch);
+}
+
+export function closePrompts() {
+    console.log('└─');
+    console.log();
+}
+
+export function section(title) {
+    console.log(color.bold(color.magentaBright(title)));
+}
+
+export function gap() {
+    console.log(branch);
+}
+
+export function warn(message) {
+    console.log(`${color.yellow('▲')}  ${message}`);
+}
+
+export function fail(message) {
+    prompts.cancel(color.red(message));
+    process.exit(1);
+}
+
+export function ready(appName, lines) {
+    console.log();
+    console.log(color.green(`App scaffolded: ${appName}`));
+    console.log();
+    section('Next steps');
+
+    for (const line of lines) {
+        console.log(line);
+    }
+}
+
+export async function confirm(options) {
+    const value = await prompts.confirm(options);
+    return unwrapPrompt(value);
+}
+
+export async function select(options) {
+    const value = await prompts.select(options);
+    return unwrapPrompt(value);
+}
+
+export async function text(options) {
+    const value = await prompts.text(options);
+    return unwrapPrompt(value);
+}
+
+function unwrapPrompt(value) {
+    if (prompts.isCancel(value)) {
+        prompts.cancel('Cancelled.');
+        process.exit(1);
+    }
+
+    return value;
+}

package/package.json

@@ -1,8 +1,12 @@
 {
     "name": "create-hsi-app",
-    "version": "0.5.2",
+    "version": "0.6.0",
     "type": "module",
     "description": "Create a new app from the frontend template.",
+    "dependencies": {
+        "@clack/prompts": "0.11.0",
+        "picocolors": "1.1.1"
+    },
     "bin": {
         "create-hsi-app": "bin/create-hsi-app.mjs"
     },