create-alistt69-kit 0.1.9 → 0.1.11

package/README.md

@@ -12,6 +12,7 @@
 [![npm version](https://img.shields.io/npm/v/create-alistt69-kit.svg)](https://www.npmjs.com/package/create-alistt69-kit)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.18-brightgreen)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![CI](https://github.com/alistt69/create-alistt69-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/alistt69/create-alistt69-kit/actions/workflows/ci.yml)
 </td>
   </tr>
 </table>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-alistt69-kit",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Opinionated React + TypeScript + Webpack project generator by alistt69",
   "keywords": [
     "create",
@@ -33,7 +33,7 @@
   ],
   "scripts": {
     "dev": "node ./bin/index.js",
-    "smoke": "node ./scripts/smoke.mjs"
+    "smoke": "node ./scripts/smoke/index.mjs"
   },
   "engines": {
     "node": ">=18.18.0"

package/src/core/apply-features.js

@@ -8,7 +8,7 @@ export async function applyFeatures({ projectPath, selectedFeatureIds }) {
             throw new Error(`Unknown feature: ${featureId}`);
         }
 
-        await feature.apply({
+        await feature.applyFeature({
             projectPath,
         });
     }

package/src/core/collect-project-info.js

@@ -9,35 +9,11 @@ import {
     text,
 } from '@clack/prompts';
 import process from 'node:process';
+import { defaultFeatureIds, featurePromptOptions, availableFeatureIdSet } from '../features/index.js';
 import { format } from '../utils/console-format.js';
 import { allowedPackageManagers } from '../utils/package-manager.js';
 
-const availableFeatures = [
-    {
-        value: 'eslint',
-        label: 'ESLint + Stylistic',
-        hint: 'JS/TS/React linting',
-    },
-    {
-        value: 'stylelint',
-        label: 'Stylelint',
-        hint: 'SCSS/CSS linting',
-    },
-    {
-        value: 'autoprefixer',
-        label: 'Autoprefixer',
-        hint: 'PostCSS vendor prefixes',
-    },
-    {
-        value: 'react-router',
-        label: 'React Router DOM',
-        hint: 'Routing + FSD-like app/pages/shared',
-    },
-];
-
-const defaultFeatureIds = availableFeatures.map((feature) => feature.value);
 const defaultPackageManager = 'npm';
-const availableFeatureIdSet = new Set(defaultFeatureIds);
 
 function handleCancel(value) {
     if (!isCancel(value)) {
@@ -130,7 +106,7 @@ export async function collectProjectInfo(cliArgs = {}) {
 
             selectedFeatureIds = handleCancel(await multiselect({
                 message: 'Remove unnecessary features',
-                options: availableFeatures,
+                options: featurePromptOptions,
                 initialValues: defaultFeatureIds,
                 required: false,
             }));

package/src/core/create-project.js

@@ -56,6 +56,7 @@ export async function createProject(cliArgs = {}) {
             projectName,
             selectedFeatureIds,
             packageManager,
+            shouldInstallDependencies,
         });
         progress.stop('README generated');
 

package/src/core/render-project-readme.js

@@ -1,9 +1,43 @@
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+
 import { featuresById } from '../features/index.js';
 import { readPackageJson } from '../utils/package-json.js';
 import { getRunScriptCommand } from '../utils/package-manager.js';
 
+const defaultTooling = [
+    {
+        title: 'React',
+        docs: 'https://react.dev/',
+        description: 'UI library',
+    },
+    {
+        title: 'TypeScript',
+        docs: 'https://www.typescriptlang.org/',
+        description: 'Static typing',
+    },
+    {
+        title: 'Webpack',
+        docs: 'https://webpack.js.org/',
+        description: 'Bundling and build pipeline',
+    },
+    {
+        title: 'SCSS Modules',
+        docs: 'https://github.com/css-modules/css-modules',
+        description: 'Scoped styling',
+    },
+    {
+        title: 'SVGR',
+        docs: 'https://react-svgr.com/',
+        description: 'SVGs as React components',
+    },
+    {
+        title: 'Webpack Bundle Analyzer',
+        docs: 'https://github.com/webpack-contrib/webpack-bundle-analyzer',
+        description: 'Bundle size inspection',
+    },
+];
+
 const scriptDescriptions = {
     dev: 'Start development server',
     start: 'Start development server',
@@ -17,6 +51,22 @@ const scriptDescriptions = {
     'lint:styles:fix': 'Run Stylelint with autofix',
 };
 
+function formatMarkdownList(items, fallback = '- None') {
+    if (items.length === 0) {
+        return fallback;
+    }
+
+    return items.join('\n');
+}
+
+function formatDefaultTooling() {
+    return formatMarkdownList(
+        defaultTooling.map(({ title, docs, description }) => (
+            `- [${title}](${docs}) — ${description}`
+        )),
+    );
+}
+
 function formatFeatureList(selectedFeatureIds) {
     if (selectedFeatureIds.length === 0) {
         return '- None';
@@ -26,7 +76,13 @@ function formatFeatureList(selectedFeatureIds) {
         .map((featureId) => {
             const feature = featuresById.get(featureId);
 
-            return `- ${feature?.title ?? featureId}`;
+            if (!feature) {
+                return `- ${featureId}`;
+            }
+
+            return feature.hint
+                ? `- ${feature.title} — ${feature.hint}`
+                : `- ${feature.title}`;
         })
         .join('\n');
 }
@@ -38,20 +94,57 @@ function formatScripts(packageManager, scripts) {
         return '_No scripts available._';
     }
 
-    return entries.map(([scriptName]) => {
-        const command = getRunScriptCommand(packageManager, scriptName);
-        const description = scriptDescriptions[scriptName] ?? 'Project script';
+    return entries
+        .map(([scriptName]) => {
+            const command = getRunScriptCommand(packageManager, scriptName);
+            const description = scriptDescriptions[scriptName] ?? 'Project script';
 
-        return `- \`${command}\` — ${description}`;
-    }).join('\n');
+            return `- \`${command}\` — ${description}`;
+        })
+        .join('\n');
+}
+
+function formatQuickStart({
+                              projectName,
+                              packageManager,
+                              shouldInstallDependencies,
+                          }) {
+    const steps = [`cd ${projectName}`];
+
+    if (!shouldInstallDependencies) {
+        steps.push(packageManager === 'yarn' ? 'yarn' : `${packageManager} install`);
+    }
+
+    steps.push(getRunScriptCommand(packageManager, 'start'));
+
+    return [
+        shouldInstallDependencies
+            ? 'Dependencies are already installed.'
+            : 'Install dependencies first, then start the development server.',
+        '',
+        '```bash',
+        ...steps,
+        '```',
+    ].join('\n');
+}
+
+function formatProjectStructure() {
+    return [
+        '- `public/` — static assets and HTML template',
+        '- `src/` — application source code',
+        '- `src/app/` — app bootstrap, providers, entry-level setup',
+        '- `src/styles/` — global styles and shared styling layer',
+        '- `config/build/` — split webpack configuration',
+    ].join('\n');
 }
 
 export async function renderProjectReadme({
-    projectPath,
-    projectName,
-    selectedFeatureIds,
-    packageManager,
-}) {
+                                              projectPath,
+                                              projectName,
+                                              selectedFeatureIds,
+                                              packageManager,
+                                              shouldInstallDependencies,
+                                          }) {
     const packageJson = await readPackageJson(projectPath);
 
     const readmeContent = [
@@ -59,10 +152,30 @@ export async function renderProjectReadme({
         '',
         'Created with `create-alistt69-kit`.',
         '',
-        '## Enabled features',
+        '## Overview',
+        '',
+        'Starter project based on React + TypeScript + Webpack with optional tooling selected during scaffolding.',
+        '',
+        '## Included by default',
+        '',
+        formatDefaultTooling(),
+        '',
+        '## Selected optional features',
         '',
         formatFeatureList(selectedFeatureIds),
         '',
+        '## Quick start',
+        '',
+        formatQuickStart({
+            projectName,
+            packageManager,
+            shouldInstallDependencies,
+        }),
+        '',
+        '## Project structure',
+        '',
+        formatProjectStructure(),
+        '',
         '## Available scripts',
         '',
         formatScripts(packageManager, packageJson.scripts ?? {}),

package/src/features/autoprefixer/index.js

@@ -1,23 +1,19 @@
-import { cp } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addDevDependencies } from '../../utils/package-json.js';
+
+import { defineFeature } from '../define-feature.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
 
-export const autoprefixerFeature = {
+export const autoprefixerFeature = defineFeature({
     id: 'autoprefixer',
     title: 'Autoprefixer',
-    apply: async ({ projectPath }) => {
-        await addDevDependencies(projectPath, {
+    hint: 'PostCSS vendor prefixes',
+    packageJson: {
+        devDependencies: {
             autoprefixer: '^10.4.21',
-        });
-
-        const filesDirPath = resolve(currentDirPath, 'files');
-
-        await cp(filesDirPath, projectPath, {
-            recursive: true,
-        });
+        },
     },
-};
+    copyFiles: resolve(currentDirPath, 'files'),
+});

package/src/features/define-feature.js

@@ -0,0 +1,33 @@
+import { cp } from 'node:fs/promises';
+
+import { patchPackageJson } from '../utils/package-json.js';
+
+export function defineFeature({
+    id,
+    title,
+    hint,
+    packageJson,
+    apply,
+    copyFiles,
+}) {
+    return {
+        id,
+        title,
+        hint,
+        async applyFeature(context) {
+            if (packageJson) {
+                await patchPackageJson(context.projectPath, packageJson);
+            }
+
+            if (copyFiles) {
+                await cp(copyFiles, context.projectPath, {
+                    recursive: true,
+                });
+            }
+
+            if (apply) {
+                await apply(context);
+            }
+        },
+    };
+}

package/src/features/eslint/index.js

@@ -1,35 +1,30 @@
-import { cp } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addDevDependencies, addScripts } from '../../utils/package-json.js';
+
+import { defineFeature } from '../define-feature.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
 
-export const eslintFeature = {
+export const eslintFeature = defineFeature({
     id: 'eslint',
     title: 'ESLint + Stylistic',
-    apply: async ({ projectPath }) => {
-        await addDevDependencies(projectPath, {
-            "eslint": "^9.0.0",
-            "@eslint/js": "^9.0.0",
-            "@stylistic/eslint-plugin": "^5.0.0",
-            "typescript-eslint": "^8.0.0",
-            "eslint-plugin-import": "^2.0.0",
-            "eslint-plugin-react": "^7.0.0",
-            "eslint-plugin-react-hooks": "^7.0.0",
-            "eslint-plugin-unused-imports": "^4.0.0"
-        });
-
-        await addScripts(projectPath, {
+    hint: 'JS/TS/React linting',
+    packageJson: {
+        devDependencies: {
+            eslint: '^9.0.0',
+            '@eslint/js': '^9.0.0',
+            '@stylistic/eslint-plugin': '^5.0.0',
+            'typescript-eslint': '^8.0.0',
+            'eslint-plugin-import': '^2.0.0',
+            'eslint-plugin-react': '^7.0.0',
+            'eslint-plugin-react-hooks': '^7.0.0',
+            'eslint-plugin-unused-imports': '^4.0.0',
+        },
+        scripts: {
             lint: 'eslint . --ext .js,.jsx,.ts,.tsx',
             'lint:fix': 'eslint . --ext .js,.jsx,.ts,.tsx --fix',
-        });
-
-        const filesDirPath = resolve(currentDirPath, 'files');
-
-        await cp(filesDirPath, projectPath, {
-            recursive: true,
-        });
+        },
     },
-};
+    copyFiles: resolve(currentDirPath, 'files'),
+});

package/src/features/index.js

@@ -12,4 +12,14 @@ export const features = [
 
 export const featuresById = new Map(
     features.map((feature) => [feature.id, feature]),
-);
+);
+
+export const featurePromptOptions = features.map((feature) => ({
+    value: feature.id,
+    label: feature.title,
+    hint: feature.hint,
+}));
+
+export const defaultFeatureIds = features.map((feature) => feature.id);
+
+export const availableFeatureIdSet = new Set(defaultFeatureIds);

package/src/features/react-router/index.js

@@ -1,23 +1,19 @@
-import { cp } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addDependencies } from '../../utils/package-json.js';
+
+import { defineFeature } from '../define-feature.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
 
-export const reactRouterFeature = {
+export const reactRouterFeature = defineFeature({
     id: 'react-router',
     title: 'React Router DOM',
-    apply: async ({ projectPath }) => {
-        await addDependencies(projectPath, {
+    hint: 'Routing + FSD-like app/pages/shared',
+    packageJson: {
+        dependencies: {
             'react-router-dom': '^7.13.2',
-        });
-
-        const filesDirPath = resolve(currentDirPath, 'files');
-
-        await cp(filesDirPath, projectPath, {
-            recursive: true,
-        });
+        },
     },
-};
+    copyFiles: resolve(currentDirPath, 'files'),
+});

package/src/features/stylelint/index.js

@@ -1,29 +1,24 @@
-import { cp } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addDevDependencies, addScripts } from '../../utils/package-json.js';
+
+import { defineFeature } from '../define-feature.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
 
-export const stylelintFeature = {
+export const stylelintFeature = defineFeature({
     id: 'stylelint',
     title: 'Stylelint',
-    apply: async ({ projectPath }) => {
-        await addDevDependencies(projectPath, {
+    hint: 'SCSS/CSS linting',
+    packageJson: {
+        devDependencies: {
             stylelint: '^17.6.0',
             'stylelint-config-standard-scss': '^17.0.0',
-        });
-
-        await addScripts(projectPath, {
+        },
+        scripts: {
             'lint:styles': 'stylelint "src/**/*.{scss,css}"',
             'lint:styles:fix': 'stylelint "src/**/*.{scss,css}" --fix',
-        });
-
-        const filesDirPath = resolve(currentDirPath, 'files');
-
-        await cp(filesDirPath, projectPath, {
-            recursive: true,
-        });
+        },
     },
-};
+    copyFiles: resolve(currentDirPath, 'files'),
+});

package/src/utils/package-json.js

@@ -1,6 +1,37 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
+function sortRecordEntries(record) {
+    if (!record) {
+        return record;
+    }
+
+    return Object.fromEntries(
+        Object.entries(record).sort(([leftName], [rightName]) => (
+            leftName.localeCompare(rightName)
+        )),
+    );
+}
+
+function mergeRecordEntries(currentRecord, entriesToAdd) {
+    if (!entriesToAdd || Object.keys(entriesToAdd).length === 0) {
+        return currentRecord;
+    }
+
+    return sortRecordEntries({
+        ...(currentRecord ?? {}),
+        ...entriesToAdd,
+    });
+}
+
+function normalizePackageJson(packageJson) {
+    packageJson.dependencies = sortRecordEntries(packageJson.dependencies);
+    packageJson.devDependencies = sortRecordEntries(packageJson.devDependencies);
+    packageJson.scripts = sortRecordEntries(packageJson.scripts);
+
+    return packageJson;
+}
+
 export async function readPackageJson(projectPath) {
     const packageJsonPath = resolve(projectPath, 'package.json');
     const content = await readFile(packageJsonPath, 'utf8');
@@ -13,61 +44,54 @@ export async function writePackageJson(projectPath, packageJson) {
 
     await writeFile(
         packageJsonPath,
-        `${JSON.stringify(packageJson, null, 4)}\n`,
+        `${JSON.stringify(normalizePackageJson(packageJson), null, 4)}\n`,
         'utf8',
     );
 }
 
-export async function addDependencies(projectPath, dependenciesToAdd) {
+export async function updatePackageJson(projectPath, updater) {
     const packageJson = await readPackageJson(projectPath);
 
-    packageJson.dependencies ??= {};
-
-    for (const [dependencyName, dependencyVersion] of Object.entries(dependenciesToAdd)) {
-        packageJson.dependencies[dependencyName] = dependencyVersion;
-    }
-
-    packageJson.dependencies = Object.fromEntries(
-        Object.entries(packageJson.dependencies).sort(([leftName], [rightName]) => (
-            leftName.localeCompare(rightName)
-        )),
-    );
+    await updater(packageJson);
 
     await writePackageJson(projectPath, packageJson);
-}
 
-export async function addDevDependencies(projectPath, dependenciesToAdd) {
-    const packageJson = await readPackageJson(projectPath);
-
-    packageJson.devDependencies ??= {};
+    return packageJson;
+}
 
-    for (const [dependencyName, dependencyVersion] of Object.entries(dependenciesToAdd)) {
-        packageJson.devDependencies[dependencyName] = dependencyVersion;
-    }
+export async function patchPackageJson(projectPath, patch) {
+    return updatePackageJson(projectPath, (packageJson) => {
+        packageJson.dependencies = mergeRecordEntries(
+            packageJson.dependencies,
+            patch.dependencies,
+        );
+
+        packageJson.devDependencies = mergeRecordEntries(
+            packageJson.devDependencies,
+            patch.devDependencies,
+        );
+
+        packageJson.scripts = mergeRecordEntries(
+            packageJson.scripts,
+            patch.scripts,
+        );
+    });
+}
 
-    packageJson.devDependencies = Object.fromEntries(
-        Object.entries(packageJson.devDependencies).sort(([leftName], [rightName]) => (
-            leftName.localeCompare(rightName)
-        )),
-    );
+export async function addDependencies(projectPath, dependenciesToAdd) {
+    return patchPackageJson(projectPath, {
+        dependencies: dependenciesToAdd,
+    });
+}
 
-    await writePackageJson(projectPath, packageJson);
+export async function addDevDependencies(projectPath, dependenciesToAdd) {
+    return patchPackageJson(projectPath, {
+        devDependencies: dependenciesToAdd,
+    });
 }
 
 export async function addScripts(projectPath, scriptsToAdd) {
-    const packageJson = await readPackageJson(projectPath);
-
-    packageJson.scripts ??= {};
-
-    for (const [scriptName, scriptValue] of Object.entries(scriptsToAdd)) {
-        packageJson.scripts[scriptName] = scriptValue;
-    }
-
-    packageJson.scripts = Object.fromEntries(
-        Object.entries(packageJson.scripts).sort(([leftName], [rightName]) => (
-            leftName.localeCompare(rightName)
-        )),
-    );
-
-    await writePackageJson(projectPath, packageJson);
+    return patchPackageJson(projectPath, {
+        scripts: scriptsToAdd,
+    });
 }