create-alistt69-kit 0.1.22 → 0.2.3

package/README.md

@@ -53,15 +53,44 @@ Setting up a frontend project from scratch usually means repeating the same stuf
 
 This starter removes that boilerplate so you can get straight to building.
 
----
+## ⚡ Generated project helpers
+
+Some optional features also add local project generators to the scaffolded app.
+
+### Page generator
+
+When `React Router DOM` is enabled, the project includes a built-in page generator.
+
+```bash
+npm run generate:page about
+```
+This will create:
+
+* `src/pages/about/index.ts`
+* `src/pages/about/lazy.ts`
+* `src/pages/about/page.tsx`
+
+If the standard router files are present, the generator will also register the page automatically in:
+
+* `src/app/providers/router/types/index.ts`
+* `src/app/providers/router/model/config/index.ts`
+* `src/app/providers/router/model/router/index.tsx`
+
+You can also configure custom paths in `scripts/generate/page.mjs`:
+* `ROUTER_TYPES_PATH`
+* `ROUTER_CONFIG_PATH`
+* `ROUTER_FILE_PATH`
+
+#### Important
+
+Route auto-registration relies on special marker comments `@route-...` inside the router files.
+Do not remove these markers unless you also want to disable automatic updates.
 
 ## 📦 Requirements
 
 - **Node.js** `18.18` or higher
 - **npm**, **pnpm**, or **yarn**
 
----
-
 ## 🔥 Quick start
 
 Create a new app interactively:
@@ -121,3 +150,5 @@ npm create alistt69-kit@latest my-app -- --defaults --overwrite
 ## 📄 License
 
 MIT — free and open for everyone.
+
+_See [LICENSE](./LICENSE)._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-alistt69-kit",
-  "version": "0.1.22",
+  "version": "0.2.3",
   "description": "Opinionated React + TypeScript + Webpack project generator by alistt69",
   "keywords": [
     "create",

package/src/core/parse-cli-args.js

@@ -28,7 +28,7 @@ export function formatHelpMessage() {
         '  create-alistt69-kit <project-name> [options]',
         '',
         'Options:',
-        '  -def, --defaults                    Skip prompts and use defaults',
+        '  -def, --defaults             Skip prompts and use defaults',
         '  --overwrite                  Overwrite target directory if it exists',
         '  --no-install                 Do not install dependencies',
         '  --features <comma-list>      Example: eslint,stylelint,react-router',

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

@@ -49,6 +49,7 @@ const scriptDescriptions = {
     'lint:fix': 'Run ESLint with autofix',
     'lint:styles': 'Run Stylelint',
     'lint:styles:fix': 'Run Stylelint with autofix',
+    'generate:page': 'Generate a new page and auto-register it in the router when available',
 };
 
 function formatMarkdownList(items, fallback = '- None') {
@@ -105,10 +106,10 @@ function formatScripts(packageManager, scripts) {
 }
 
 function formatQuickStart({
-                              projectName,
-                              packageManager,
-                              shouldInstallDependencies,
-                          }) {
+    projectName,
+    packageManager,
+    shouldInstallDependencies,
+}) {
     const steps = [`cd ${projectName}`];
 
     if (!shouldInstallDependencies) {
@@ -128,24 +129,64 @@ function formatQuickStart({
     ].join('\n');
 }
 
-function formatProjectStructure() {
-    return [
+function formatProjectStructure(selectedFeatureIds) {
+    const items = [
         '- `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');
+    ];
+
+    if (selectedFeatureIds.includes('react-router')) {
+        items.splice(3, 0, '- `src/pages/` — route-level pages');
+    }
+
+    return items.join('\n');
+}
+
+function formatFeatureSpecificSections({ selectedFeatureIds, packageManager }) {
+    const sections = [];
+
+    if (selectedFeatureIds.includes('react-router')) {
+        sections.push([
+            '## Page generator',
+            '',
+            'When `React Router DOM` is enabled, you can scaffold a new page with one command.',
+            '',
+            '```bash',
+            `${getRunScriptCommand(packageManager, 'generate:page')} about`,
+            '```',
+            '',
+            'This creates:',
+            '',
+            '- `src/pages/about/index.ts`',
+            '- `src/pages/about/lazy.ts`',
+            '- `src/pages/about/page.tsx`',
+            '',
+            'If the standard router files are still present, the generator also updates:',
+            '',
+            '- `src/app/providers/router/types/index.ts`',
+            '- `src/app/providers/router/model/config/index.ts`',
+            '- `src/app/providers/router/model/router/index.tsx`',
+        ].join('\n'));
+    }
+
+    return sections.join('\n\n');
 }
 
 export async function renderProjectReadme({
-                                              projectPath,
-                                              projectName,
-                                              selectedFeatureIds,
-                                              packageManager,
-                                              shouldInstallDependencies,
-                                          }) {
+    projectPath,
+    projectName,
+    selectedFeatureIds,
+    packageManager,
+    shouldInstallDependencies,
+}) {
     const packageJson = await readPackageJson(projectPath);
+    const featureSpecificSections = formatFeatureSpecificSections({
+        selectedFeatureIds,
+        packageManager,
+    });
 
     const readmeContent = [
         `# ${projectName}`,
@@ -174,11 +215,12 @@ export async function renderProjectReadme({
         '',
         '## Project structure',
         '',
-        formatProjectStructure(),
+        formatProjectStructure(selectedFeatureIds),
         '',
         '## Available scripts',
         '',
         formatScripts(packageManager, packageJson.scripts ?? {}),
+        ...(featureSpecificSections ? ['', featureSpecificSections] : []),
     ].join('\n');
 
     await writeFile(

package/src/features/react-router/files/scripts/generate/page.mjs

@@ -0,0 +1,341 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const ROUTER_TYPES_PATH = path.join(
+    'src',
+    'app',
+    'providers',
+    'router',
+    'types',
+    'index.ts',
+);
+
+const ROUTER_CONFIG_PATH = path.join(
+    'src',
+    'app',
+    'providers',
+    'router',
+    'model',
+    'config',
+    'index.ts',
+);
+
+const ROUTER_FILE_PATH = path.join(
+    'src',
+    'app',
+    'providers',
+    'router',
+    'model',
+    'router',
+    'index.tsx',
+);
+
+async function main() {
+    const rawPageName = process.argv[2];
+
+    if (!rawPageName) {
+        printUsageAndExit();
+    }
+
+    const pageSlug = normalizePageSlug(rawPageName);
+
+    if (!pageSlug) {
+        fail('Page name cannot be empty.');
+    }
+
+    const pageDirPath = path.join(process.cwd(), 'src', 'pages', pageSlug);
+
+    if (await pathExists(pageDirPath)) {
+        fail(`Page "${pageSlug}" already exists: ${toRelativeProjectPath(pageDirPath)}`);
+    }
+
+    const pageMeta = buildPageMeta(pageSlug);
+
+    await createPageFiles(pageDirPath, pageMeta);
+
+    const autoRegisterResult = await autoRegisterPage(pageMeta);
+
+    console.log(`✔ Page "${pageSlug}" created.`);
+
+    if (autoRegisterResult.status === 'registered') {
+        console.log('✔ Route registration updated.');
+        return;
+    }
+
+    console.log(`ℹ ${autoRegisterResult.message}`);
+}
+
+function printUsageAndExit() {
+    console.error('Usage: npm run generate:page -- <page-name>');
+    console.error('Example: npm run generate:page -- about');
+    process.exit(1);
+}
+
+function fail(message) {
+    console.error(`✖ ${message}`);
+    process.exit(1);
+}
+
+function normalizePageSlug(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[_\s]+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+
+function buildPageMeta(pageSlug) {
+    return {
+        pageSlug,
+        pageComponentName: toPascalCase(pageSlug),
+        pageTitle: toTitleCase(pageSlug),
+        routeEnumKey: toScreamingSnake(pageSlug),
+    };
+}
+
+function toPascalCase(value) {
+    return value
+        .split('-')
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join('');
+}
+
+function toScreamingSnake(value) {
+    return value
+        .split('-')
+        .filter(Boolean)
+        .join('_')
+        .toUpperCase();
+}
+
+function toTitleCase(value) {
+    return value
+        .split('-')
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join(' ');
+}
+
+async function createPageFiles(pageDirPath, pageMeta) {
+    const { pageComponentName, pageTitle } = pageMeta;
+
+    await mkdir(pageDirPath, {
+        recursive: true,
+    });
+
+    await writeFile(
+        path.join(pageDirPath, 'index.ts'),
+        `export { Lazy${pageComponentName} as ${pageComponentName} } from './lazy';\n`,
+        'utf8',
+    );
+
+    await writeFile(
+        path.join(pageDirPath, 'lazy.ts'),
+        [
+            "import { lazy } from 'react';",
+            '',
+            `export const Lazy${pageComponentName} = lazy(() => import('./page'));`,
+            '',
+        ].join('\n'),
+        'utf8',
+    );
+
+    await writeFile(
+        path.join(pageDirPath, 'page.tsx'),
+        [
+            `function ${pageComponentName}Page() {`,
+            '    return (',
+            `        <h2>${pageTitle} page</h2>`,
+            '    );',
+            '}',
+            '',
+            `export default ${pageComponentName}Page;`,
+            '',
+        ].join('\n'),
+        'utf8',
+    );
+}
+
+async function autoRegisterPage(pageMeta) {
+    const projectRoot = process.cwd();
+
+    const typesFilePath = path.join(projectRoot, ROUTER_TYPES_PATH);
+    const configFilePath = path.join(projectRoot, ROUTER_CONFIG_PATH);
+    const routerFilePath = path.join(projectRoot, ROUTER_FILE_PATH);
+
+    const [hasTypesFile, hasConfigFile, hasRouterFile] = await Promise.all([
+        pathExists(typesFilePath),
+        pathExists(configFilePath),
+        pathExists(routerFilePath),
+    ]);
+
+    if (!hasTypesFile || !hasConfigFile || !hasRouterFile) {
+        const missingFiles = [
+            !hasTypesFile ? ROUTER_TYPES_PATH : null,
+            !hasConfigFile ? ROUTER_CONFIG_PATH : null,
+            !hasRouterFile ? ROUTER_FILE_PATH : null,
+        ].filter(Boolean);
+
+        return {
+            status: 'skipped',
+            message: `Route auto-registration skipped. Missing files: ${missingFiles.join(', ')}`,
+        };
+    }
+
+    await insertRouteEnum(typesFilePath, pageMeta);
+    await insertRouteConfig(configFilePath, pageMeta);
+    await insertRouteImport(routerFilePath, pageMeta);
+    await insertRouteDefinition(routerFilePath, pageMeta);
+
+    return {
+        status: 'registered',
+    };
+}
+
+async function insertRouteEnum(filepath, pageMeta) {
+    await insertBeforeMarkerLine({
+        filepath,
+        marker: '// @route-enum',
+        block: `${pageMeta.routeEnumKey} = '${pageMeta.pageSlug}',`,
+    });
+}
+
+async function insertRouteConfig(filepath, pageMeta) {
+    await insertBeforeMarkerLine({
+        filepath,
+        marker: '// @route-config',
+        block: [
+            `[ERoutePath.${pageMeta.routeEnumKey}]: {`,
+            `    path: ERoutePath.${pageMeta.routeEnumKey},`,
+            `    title: '${pageMeta.pageTitle}',`,
+            '},',
+        ].join('\n'),
+    });
+}
+
+async function insertRouteImport(filepath, pageMeta) {
+    await insertBeforeMarkerLine({
+        filepath,
+        marker: '/* @route-imports */',
+        block: `import { ${pageMeta.pageComponentName} } from '../../../../../pages/${pageMeta.pageSlug}';`,
+    });
+}
+
+async function insertRouteDefinition(filepath, pageMeta) {
+    await insertBeforeMarkerLine({
+        filepath,
+        marker: '{/* @route-routes */}',
+        block: `<Route path={ERoutePath.${pageMeta.routeEnumKey}} element={<${pageMeta.pageComponentName} />} />`,
+    });
+}
+
+async function insertBeforeMarkerLine({ filepath, marker, block }) {
+    const fileContent = await readFile(filepath, 'utf8');
+    const eol = detectEol(fileContent);
+    const hadTrailingNewline = /\r?\n$/.test(fileContent);
+
+    const lines = fileContent.split(/\r?\n/);
+
+    if (hadTrailingNewline && lines.at(-1) === '') {
+        lines.pop();
+    }
+
+    const markerLineIndex = lines.findIndex((line) => line.includes(marker));
+
+    if (markerLineIndex === -1) {
+        fail(`Marker "${marker}" not found in ${toRelativeProjectPath(filepath)}`);
+    }
+
+    const markerLine = lines[markerLineIndex];
+    const baseIndent = getLineIndent(markerLine);
+    const normalizedBlock = indentBlock(block, baseIndent);
+    const normalizedBlockLines = normalizedBlock.split('\n');
+
+    if (blockAlreadyInserted(lines, normalizedBlockLines)) {
+        return;
+    }
+
+    lines.splice(markerLineIndex, 0, ...normalizedBlockLines);
+
+    let nextContent = lines.join(eol);
+
+    if (hadTrailingNewline) {
+        nextContent += eol;
+    }
+
+    await writeFile(filepath, nextContent, 'utf8');
+}
+
+function detectEol(content) {
+    return content.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function getLineIndent(line) {
+    const match = line.match(/^\s*/);
+
+    return match ? match[0] : '';
+}
+
+function indentBlock(block, baseIndent) {
+    const rawLines = block.split('\n');
+
+    return rawLines
+        .map((line) => {
+            if (!line.trim()) {
+                return '';
+            }
+
+            const lineIndentSize = countLeadingSpaces(line);
+            const relativeIndentLevel = Math.floor(lineIndentSize / 4);
+            const relativeIndent = ' '.repeat(relativeIndentLevel * 4);
+
+            return `${baseIndent}${relativeIndent}${line.trimStart()}`;
+        })
+        .join('\n');
+}
+
+function countLeadingSpaces(line) {
+    const match = line.match(/^ */);
+
+    return match ? match[0].length : 0;
+}
+
+function blockAlreadyInserted(lines, normalizedBlockLines) {
+    const comparableLines = normalizedBlockLines.filter((line) => line.trim() !== '');
+
+    if (comparableLines.length === 0) {
+        return false;
+    }
+
+    for (let index = 0; index <= lines.length - comparableLines.length; index += 1) {
+        const currentSlice = lines.slice(index, index + comparableLines.length);
+
+        if (currentSlice.join('\n') === comparableLines.join('\n')) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+async function pathExists(filepath) {
+    try {
+        await access(filepath);
+        return true;
+    } catch (_) {
+        return false;
+    }
+}
+
+function toRelativeProjectPath(filepath) {
+    return path.relative(process.cwd(), filepath) || '.';
+}
+
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+
+    fail(message);
+});

package/src/features/react-router/files/src/app/providers/router/model/config/index.ts

@@ -5,4 +5,5 @@ export const routesConfig: Record<Exclude<ERoutePath, ERoutePath.ERROR>, IRouteC
         path: ERoutePath.MAIN,
         title: 'Main',
     },
+    // @route-config
 };

package/src/features/react-router/files/src/app/providers/router/model/router/index.tsx

@@ -1,7 +1,9 @@
 import { ComponentType, ReactNode } from 'react';
 import { createBrowserRouter, createRoutesFromElements, Route } from 'react-router-dom';
+import { ERoutePath } from '../../types';
 import { Error } from '../../../../../pages/error';
 import { Main } from '../../../../../pages/main';
+/* @route-imports */
 import AppLayout from '../../ui/app';
 
 export const getRouter = (ErrorBoundary: ComponentType<{ children: ReactNode }>) => createBrowserRouter(
@@ -15,7 +17,8 @@ export const getRouter = (ErrorBoundary: ComponentType<{ children: ReactNode }>)
             )}
         >
             <Route index element={<Main />} />
-            <Route path="*" element={<Error />} />
+            {/* @route-routes */}
+            <Route path={ERoutePath.ERROR} element={<Error />} />
         </Route>,
     ),
 );

package/src/features/react-router/files/src/app/providers/router/types/index.ts

@@ -1,5 +1,6 @@
 export enum ERoutePath {
     MAIN = '',
+    // @route-enum
     ERROR = '*',
 }
 

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

@@ -14,6 +14,9 @@ export const reactRouterFeature = defineFeature({
         dependencies: {
             'react-router-dom': '^7.13.2',
         },
+        scripts: {
+            'generate:page': 'node ./scripts/generate/page.mjs',
+        },
     },
     copyFiles: resolve(currentDirPath, 'files'),
 });