@lomray/create-ssr-app 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lomray Software
+
+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,144 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Lomray-Software/vite-ssr-boost/prod/logo.png" width="160" alt="Lomray Vite SSR Boost" />
+</p>
+
+<h1 align="center">@lomray/create-ssr-app</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lomray/create-ssr-app"><img src="https://img.shields.io/npm/v/@lomray/create-ssr-app" alt="npm version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/Lomray-Software/create-ssr-app" alt="MIT license" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@lomray/create-ssr-app" alt="Node.js version" /></a>
+</p>
+
+Create a React application with Vite SSR Boost from the official Lomray templates.  
+Start with minimal SSR, the full reference app, a Fastify production server, or localization.
+
+## Usage
+
+Requires Node.js **22.12.0 or newer**.
+
+```sh
+npm create @lomray/ssr-app@latest my-app
+pnpm create @lomray/ssr-app my-app
+yarn create @lomray/ssr-app my-app
+bun create @lomray/ssr-app my-app
+```
+
+You can also run `npx @lomray/create-ssr-app my-app` or the installed `create-ssr-app` binary.
+For npm, put flags after `--` so npm forwards them to the scaffolder:
+
+```sh
+npm create @lomray/ssr-app@latest my-app -- --template custom-server --no-install --no-git -y
+npx @lomray/create-ssr-app my-app --template localization
+```
+
+On a terminal, missing values prompt for the directory, a numbered template choice, dependency
+installation, and git initialization. Empty answers accept defaults. With `--yes` or non-TTY stdin,
+the CLI uses flags and defaults without prompting. Package manager selection follows
+`npm_config_user_agent`, falling back to npm.
+
+## Options
+
+| Argument / option          | Default                   | Description                                                                                                             |
+| -------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `[directory]`              | `my-ssr-app`              | Destination directory.                                                                                                  |
+| `-t, --template <name>`    | `minimal`                 | `full`, `minimal`, `custom-server`, or `localization`.                                                                  |
+| `--ref <branch\|tag\|sha>` | Template branch           | Advanced: use any git ref in the template repository, overriding the template mapping and skipping the template prompt. |
+| `--package-manager <name>` | Detected, otherwise `npm` | `npm`, `pnpm`, `yarn`, or `bun`.                                                                                        |
+| `--no-install`             | Install                   | Skip installation and print the install command in Next steps.                                                          |
+| `--no-git`                 | Initialize git            | Skip git initialization; remove `.husky/` and `scripts.prepare`.                                                        |
+| `--force`                  | Off                       | Allow a non-empty destination, overwriting matching template files and retaining unrelated existing files.              |
+| `-y, --yes`                | Off                       | Accept defaults without prompts.                                                                                        |
+| `-h, --help`               | Off                       | Print help.                                                                                                             |
+| `-v, --version`            | Off                       | Print the package version.                                                                                              |
+
+Git initialization is also skipped if git is unavailable or the destination is already inside a
+repository; in both cases, `.husky/` and `scripts.prepare` are removed from the copied template.
+Existing destination symlinks that conflict with template paths are rejected even with `--force`.
+
+## Templates
+
+These descriptions match the [template repository](https://github.com/Lomray-Software/vite-template/tree/prod).
+See the [Vite SSR Boost documentation](https://lomray-software.github.io/vite-ssr-boost/) for development,
+SSR behavior, and deployment.
+
+| Template        | Branch                                                                                                 | What it shows                                                                                                                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `full`          | [`prod`](https://github.com/Lomray-Software/vite-template/tree/prod)                                   | Streaming SSR, MobX, consistent Suspense, meta tags and route management                                                                                                                          |
+| `minimal`       | [`example/minimal`](https://github.com/Lomray-Software/vite-template/tree/example/minimal)             | Six runtime dependencies, loaders, a lazy route with CSS, redirect, client-only route and 404, plus the SPA-to-SSR file diff                                                                      |
+| `custom-server` | [`example/custom-server`](https://github.com/Lomray-Software/vite-template/tree/example/custom-server) | Development through the managed CLI, production through an application-owned Fastify server with static assets, compression and Early Hints; dual export of the managed entry and a Fetch handler |
+| `localization`  | [`example/localization`](https://github.com/Lomray-Software/vite-template/tree/example/localization)   | i18next with the language chosen on the server from the cookie or Accept-Language, transferred to the client before hydration, and a cookie-based switcher                                        |
+
+## How it works
+
+1. Downloads `https://codeload.github.com/Lomray-Software/vite-template/tar.gz/refs/heads/<branch>`
+   with Node's global `fetch`. For an explicit `--ref`, a branch endpoint returning 404 falls back to
+   `https://codeload.github.com/Lomray-Software/vite-template/tar.gz/<ref>` for tags and commits.
+2. Decompresses with `node:zlib` and reads the tar archive using this package's own reader.
+   It supports ustar, pax, GNU long names, directories, regular files, and permission bits. It strips
+   the enclosing archive directory, skips global pax metadata and links, and rejects paths that
+   escape the destination. Source `.git` metadata is excluded. There are **zero runtime dependencies**.
+3. Removes `.github/`, `renovate.json`, `CHANGELOG.md`, `LICENSE`, and `SECURITY.md` from the template.
+   When git initialization is skipped, it also removes `.husky/` and `scripts.prepare`.
+   It keeps `vercel.json`, `amplify.yml`, `Dockerfile`, and the other project files.
+4. Sets `package.json`'s name to a valid npm name derived from the destination basename and its
+   version to `0.1.0`. It deletes `description`, `repository`, `homepage`, `bugs`, `author`, and
+   `keywords`, preserving `private` and other fields. The scaffolder does not edit lockfiles.
+5. When enabled and available, runs `git init --initial-branch=main` and creates
+   `Initial commit from @lomray/create-ssr-app` before installing dependencies. The initial commit
+   bypasses hooks and signing; it uses the configured git identity, with `create-ssr-app` /
+   `create-ssr-app@localhost` as a fallback if none is configured.
+6. Runs `npm ci` when npm is selected and `package-lock.json` exists; otherwise runs the selected
+   manager's `install` command. Prints each command, then Next steps with the selected manager's
+   `run develop` command and the documentation link. A package manager may update its own lockfile.
+
+Colors use ANSI codes only on TTY output and are disabled whenever `NO_COLOR` is defined.
+Exit codes are `0` for success, `1` for input, source, or command failures, and `2` for unexpected errors.
+
+## Offline and proxies
+
+Use a local `.tar.gz` archive (with an enclosing directory, like GitHub's archives) or a directory
+containing the template's `package.json`:
+
+```sh
+CREATE_SSR_APP_SOURCE=/path/to/template.tar.gz npx @lomray/create-ssr-app my-app --no-install -y
+CREATE_SSR_APP_SOURCE=/path/to/vite-template npx @lomray/create-ssr-app my-app --no-install --no-git -y
+```
+
+This replaces the download regardless of `--template` or `--ref`. A directory is copied without
+changing the source; symlinks and `.git` metadata are skipped. Use an already installed CLI or a local
+checkout (`npm ci && npm run build`, then `node bin/create-ssr-app.mjs`) if npm itself is also offline.
+
+The CLI does not implement proxy handling. `HTTPS_PROXY` alone is not automatically honored by
+global `fetch`. On Node.js 22.23.2, a local proxy probe confirmed that `HTTPS_PROXY` alone was ignored
+and `NODE_USE_ENV_PROXY=1` enabled proxy routing. Node added this opt-in for `fetch` in 22.21.0;
+see the [Node.js release notes](https://github.com/nodejs/nodejs.org/blob/main/apps/site/pages/en/blog/release/v22.21.0.md).
+
+```sh
+NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.example.com:8080 npx @lomray/create-ssr-app my-app
+```
+
+On older supported Node versions, upgrade to a runtime that honors proxy environment variables
+or download the archive separately and use `CREATE_SSR_APP_SOURCE`.
+
+## Contributing
+
+Use the Node version in `.nvmrc` for the development tools:
+
+```sh
+npm ci
+npm run lint:check
+npm run ts:check
+npm test
+npm run build
+npm pack --dry-run
+CREATE_SSR_APP_E2E=1 npm run test:e2e
+```
+
+The opt-in e2e suite downloads all four GitHub templates and installs and builds the minimal app.
+Releases use semantic-release: `prod` publishes to npm's `latest` channel and `staging` publishes
+`beta` prereleases. CI expects `NPM_TOKEN` and `GITHUB_TOKEN` for releases.
+
+## License
+
+[MIT](LICENSE) — Lomray Software.

package/bin/create-ssr-app.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+
+if (major < 22 || (major === 22 && minor < 12)) {
+  console.error(
+    `Error: Unsupported Node.js ${process.versions.node}; @lomray/create-ssr-app requires Node.js >=22.12.0.`,
+  );
+  process.exitCode = 1;
+} else {
+  try {
+    const { run } = await import('../lib/index.js');
+
+    process.exitCode = await run();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    console.error(`Error: ${message.replace(/[\r\n\x1b]+/g, ' ').replace(/[.!]+$/, '')}.`);
+    process.exitCode = 2;
+  }
+}

package/lib/commands.js

@@ -0,0 +1,68 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { dirname } from 'node:path';
+import { UserError } from './errors.js';
+import { statIfExists } from './files.js';
+import { displayCommand } from './package-manager.js';
+export const runCommand = async (command, cwd, log) => {
+    const [executable, ...args] = command;
+    if (!executable) {
+        throw new Error('Cannot run an empty command');
+    }
+    log(`Running: ${displayCommand(command)}`);
+    await new Promise((resolve, reject) => {
+        const child = spawn(executable, args, {
+            cwd,
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        child.on('error', (error) => {
+            reject(new UserError(`Unable to run ${executable}: ${error.message}`));
+        });
+        child.on('exit', (code, signal) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new UserError(`${displayCommand(command)} failed (${signal ? `signal ${signal}` : `exit code ${code}`})`));
+            }
+        });
+    });
+};
+export const shouldInitializeGit = async (directory, enabled, log) => {
+    if (!enabled) {
+        return false;
+    }
+    if (spawnSync('git', ['--version'], { stdio: 'ignore' }).status !== 0) {
+        log('Git is unavailable; skipping git initialization.');
+        return false;
+    }
+    let ancestor = directory;
+    while (!(await statIfExists(ancestor))) {
+        ancestor = dirname(ancestor);
+    }
+    if (spawnSync('git', ['rev-parse', '--git-dir'], { cwd: ancestor, stdio: 'ignore' }).status === 0) {
+        log('The destination is already inside a repository; skipping git initialization.');
+        return false;
+    }
+    return true;
+};
+export const initializeGit = async (directory, log) => {
+    await runCommand(['git', 'init', '--initial-branch=main'], directory, log);
+    await runCommand(['git', 'add', '--all'], directory, log);
+    const config = [
+        '-c',
+        'commit.gpgsign=false',
+        '-c',
+        `core.hooksPath=${process.platform === 'win32' ? 'NUL' : '/dev/null'}`,
+    ];
+    for (const [key, fallback] of [
+        ['user.name', 'create-ssr-app'],
+        ['user.email', 'create-ssr-app@localhost'],
+    ]) {
+        const value = spawnSync('git', ['config', '--get', key], { cwd: directory, encoding: 'utf8' });
+        if (!value.stdout?.trim()) {
+            config.push('-c', `${key}=${fallback}`);
+        }
+    }
+    await runCommand(['git', ...config, 'commit', '-m', 'Initial commit from @lomray/create-ssr-app'], directory, log);
+};

package/lib/errors.js

@@ -0,0 +1,12 @@
+export class UserError extends Error {
+}
+export const errorCause = (error) => {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const cause = error.cause instanceof Error ? `: ${error.cause.message}` : '';
+    return `${error.message}${cause}`;
+};
+export const errorSentence = (error) => `Error: ${errorCause(error)
+    .replace(/[\r\n\x1b]+/g, ' ')
+    .replace(/[.!]+$/, '')}.`;

package/lib/files.js

@@ -0,0 +1,79 @@
+import { chmod, copyFile, lstat, mkdir, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { UserError } from './errors.js';
+export const statIfExists = async (path) => {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+};
+export const checkDestination = async (directory, force) => {
+    const info = await statIfExists(directory);
+    if (!info) {
+        return;
+    }
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+        throw new UserError(`Destination "${directory}" must be a directory, not a file or symlink`);
+    }
+    if (!force && (await readdir(directory)).length > 0) {
+        throw new UserError(`Directory "${directory}" is not empty; use --force to allow existing files`);
+    }
+};
+const collectEntries = async (source, target) => {
+    const entries = [];
+    for (const entry of await readdir(source, { withFileTypes: true })) {
+        // Repository metadata and links must never be imported from an offline checkout.
+        if (entry.name === '.git' || entry.isSymbolicLink()) {
+            continue;
+        }
+        const sourcePath = join(source, entry.name);
+        const targetPath = join(target, entry.name);
+        const info = await lstat(sourcePath);
+        if (!info.isFile() && !info.isDirectory()) {
+            continue;
+        }
+        const existing = await statIfExists(targetPath);
+        if (existing &&
+            (existing.isSymbolicLink() ||
+                existing.isDirectory() !== info.isDirectory() ||
+                (!existing.isDirectory() && !existing.isFile()))) {
+            throw new UserError(`Destination entry "${targetPath}" conflicts with the template or is a symlink`);
+        }
+        entries.push({
+            source: sourcePath,
+            target: targetPath,
+            directory: info.isDirectory(),
+            mode: info.mode & 0o777,
+        });
+        if (info.isDirectory()) {
+            entries.push(...(await collectEntries(sourcePath, targetPath)));
+        }
+    }
+    return entries;
+};
+export const copyDirectory = async (source, target) => {
+    await checkDestination(target, true);
+    const entries = await collectEntries(source, target);
+    await mkdir(target, { recursive: true });
+    for (const entry of entries) {
+        if (entry.directory) {
+            await mkdir(entry.target, { recursive: true });
+        }
+        else {
+            // Replace the entry itself so an existing hard link cannot modify an outside file.
+            await rm(entry.target, { force: true });
+            await copyFile(entry.source, entry.target);
+            await chmod(entry.target, entry.mode);
+        }
+    }
+    for (const entry of entries.reverse()) {
+        if (entry.directory) {
+            await chmod(entry.target, entry.mode);
+        }
+    }
+};

package/lib/index.js

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { initializeGit, runCommand, shouldInitializeGit } from './commands.js';
+import { UserError, errorSentence } from './errors.js';
+import { checkDestination, copyDirectory, statIfExists } from './files.js';
+import { parseArgs, resolveOptions } from './options.js';
+import { developCommand, displayCommand, installCommand, quoteArgument, } from './package-manager.js';
+import { postProcess, removeTemplateMetadata } from './project.js';
+import { loadSource } from './source.js';
+import { templates } from './templates.js';
+const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const docsUrl = 'https://lomray-software.github.io/vite-ssr-boost/';
+export const colorize = (text, code, isTTY = Boolean(process.stdout.isTTY), environment = process.env) => isTTY && environment.NO_COLOR === undefined ? `\u001B[${code}m${text}\u001B[0m` : text;
+export const help = `${metadata.name} v${metadata.version}
+
+Usage:
+  npm create @lomray/ssr-app@latest [directory] [-- options]
+  npx @lomray/create-ssr-app [directory] [options]
+
+Options:
+  -t, --template <name>       full | minimal | custom-server | localization (default: minimal)
+      --ref <branch|tag|sha>  Override the template branch with any template repository git ref
+      --package-manager <pm> npm | pnpm | yarn | bun (detected from npm_config_user_agent; otherwise npm)
+      --no-install           Skip installing dependencies
+      --no-git               Skip git initialization and remove Husky/prepare
+      --force                Allow a non-empty directory; overwrite matching template files
+  -y, --yes                  Accept defaults without prompts
+  -h, --help                 Show this help
+  -v, --version              Show the version
+
+The default directory is my-ssr-app. Prompts run only when stdin is a TTY and --yes is absent.
+CREATE_SSR_APP_SOURCE=<directory|archive.tar.gz> uses a local template instead of GitHub.
+Requires Node.js >=22.12.0.
+Documentation: ${docsUrl}`;
+export const nextSteps = (options, hasNpmLockfile) => {
+    const directory = options.directory.startsWith('-')
+        ? `./${options.directory}`
+        : options.directory;
+    const commands = [`cd ${quoteArgument(directory)}`];
+    if (!options.install) {
+        commands.push(displayCommand(installCommand(options.packageManager, hasNpmLockfile)));
+    }
+    commands.push(displayCommand(developCommand(options.packageManager)));
+    return `\nNext steps:\n${commands.map((command) => `  ${command}`).join('\n')}\n\nDocumentation: ${docsUrl}`;
+};
+export const scaffold = async (options, log = console.log, source = process.env.CREATE_SSR_APP_SOURCE) => {
+    const directory = resolve(options.directory);
+    await checkDestination(directory, options.force);
+    log(`Template: ${options.template} (${options.ref ?? templates[options.template].branch}${options.ref ? ', --ref override' : ''})`);
+    log(`Directory: ${options.directory}`);
+    const shouldUseGit = await shouldInitializeGit(directory, options.git, log);
+    const temporary = await mkdtemp(join(tmpdir(), 'create-ssr-app-'));
+    try {
+        const staging = join(temporary, 'template');
+        await loadSource(staging, options.ref ?? templates[options.template].branch, Boolean(options.ref), source);
+        await postProcess(staging, directory, shouldUseGit);
+        // Recheck after the download in case another process populated the destination.
+        await checkDestination(directory, options.force);
+        await copyDirectory(staging, directory);
+        await removeTemplateMetadata(directory, shouldUseGit);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    if (shouldUseGit) {
+        await initializeGit(directory, log);
+    }
+    const hasNpmLockfile = Boolean(await statIfExists(join(directory, 'package-lock.json')));
+    if (options.install) {
+        await runCommand(installCommand(options.packageManager, hasNpmLockfile), directory, log);
+    }
+    log(colorize('\nProject created.', 32));
+    log(nextSteps(options, hasNpmLockfile));
+};
+export const run = async (args = process.argv.slice(2)) => {
+    try {
+        const parsed = parseArgs(args, process.env.npm_config_user_agent);
+        if (parsed.options.help) {
+            console.log(help);
+            return 0;
+        }
+        if (parsed.options.version) {
+            console.log(metadata.version);
+            return 0;
+        }
+        console.log(colorize(`${metadata.name} v${metadata.version}\n`, 36));
+        let { options } = parsed;
+        if (process.stdin.isTTY && !options.yes) {
+            const reader = createInterface({ input: process.stdin, output: process.stdout });
+            const controller = new AbortController();
+            const cancel = () => controller.abort();
+            reader.on('SIGINT', cancel);
+            reader.on('close', cancel);
+            try {
+                options = await resolveOptions(parsed, true, (question) => reader.question(question, { signal: controller.signal }));
+            }
+            catch (error) {
+                if (controller.signal.aborted) {
+                    throw new UserError('Project creation was cancelled');
+                }
+                throw error;
+            }
+            finally {
+                reader.close();
+            }
+        }
+        await scaffold(options);
+        return 0;
+    }
+    catch (error) {
+        console.error(errorSentence(error));
+        return error instanceof UserError ? 1 : 2;
+    }
+};

package/lib/options.js

@@ -0,0 +1,101 @@
+import { parseArgs as parseNodeArgs } from 'node:util';
+import { UserError, errorCause } from './errors.js';
+import { detectPackageManager, isPackageManager } from './package-manager.js';
+import { isTemplate, templates } from './templates.js';
+export const parseArgs = (args, userAgent) => {
+    let parsed;
+    try {
+        parsed = parseNodeArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                template: { type: 'string', short: 't' },
+                ref: { type: 'string' },
+                'package-manager': { type: 'string' },
+                'no-install': { type: 'boolean' },
+                'no-git': { type: 'boolean' },
+                force: { type: 'boolean' },
+                yes: { type: 'boolean', short: 'y' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        });
+    }
+    catch (error) {
+        throw new UserError(errorCause(error));
+    }
+    const { values, positionals } = parsed;
+    const template = values.template ?? 'minimal';
+    const packageManager = values['package-manager'] ?? detectPackageManager(userAgent);
+    if (positionals.length > 1) {
+        throw new UserError('Expected at most one project directory');
+    }
+    if (positionals[0] !== undefined && !positionals[0].trim()) {
+        throw new UserError('The project directory cannot be empty');
+    }
+    if (!isTemplate(template)) {
+        throw new UserError(`Unknown template "${template}"; choose ${Object.keys(templates).join(', ')}`);
+    }
+    if (!isPackageManager(packageManager)) {
+        throw new UserError(`Unknown package manager "${packageManager}"; choose npm, pnpm, yarn or bun`);
+    }
+    if (values.ref !== undefined && (!values.ref.trim() || /[\x00-\x20\x7f]/u.test(values.ref))) {
+        throw new UserError('The template ref must be a non-empty git branch, tag or SHA without spaces');
+    }
+    const provided = new Set(Object.keys(values));
+    if (positionals[0] !== undefined) {
+        provided.add('directory');
+    }
+    return {
+        options: {
+            directory: positionals[0] ?? 'my-ssr-app',
+            template,
+            ref: values.ref,
+            packageManager,
+            install: !values['no-install'],
+            git: !values['no-git'],
+            force: values.force ?? false,
+            yes: values.yes ?? false,
+            help: values.help ?? false,
+            version: values.version ?? false,
+        },
+        provided,
+    };
+};
+const confirm = async (ask, question) => {
+    const answer = (await ask(`${question} (Y/n) `)).trim().toLowerCase();
+    if (['', 'y', 'yes'].includes(answer)) {
+        return true;
+    }
+    if (['n', 'no'].includes(answer)) {
+        return false;
+    }
+    throw new UserError('Please answer yes or no');
+};
+export const resolveOptions = async ({ options: defaults, provided }, isTTY, ask) => {
+    const options = { ...defaults };
+    if (!isTTY || options.yes || options.help || options.version) {
+        return options;
+    }
+    if (!provided.has('directory')) {
+        options.directory = (await ask('Project directory (my-ssr-app): ')).trim() || options.directory;
+    }
+    if (!provided.has('template') && !provided.has('ref')) {
+        const names = Object.keys(templates);
+        const choices = names.map((name, index) => `  ${index + 1}. ${name}: ${templates[name].description}`);
+        const answer = (await ask(`Templates:\n${choices.join('\n')}\nTemplate (2, minimal): `)).trim();
+        const chosen = /^\d+$/u.test(answer) ? names[Number(answer) - 1] : answer || options.template;
+        if (!chosen || !isTemplate(chosen)) {
+            throw new UserError(`Unknown template "${answer}"; choose a template name or number 1–4`);
+        }
+        options.template = chosen;
+    }
+    if (!provided.has('no-install')) {
+        options.install = await confirm(ask, 'Install dependencies?');
+    }
+    if (!provided.has('no-git')) {
+        options.git = await confirm(ask, 'Initialize git?');
+    }
+    return options;
+};

package/lib/package-manager.js

@@ -0,0 +1,21 @@
+export const packageManagers = ['npm', 'pnpm', 'yarn', 'bun'];
+export const isPackageManager = (value) => packageManagers.some((manager) => manager === value);
+export const detectPackageManager = (userAgent = '') => {
+    const manager = userAgent.split('/')[0] ?? '';
+    return isPackageManager(manager) ? manager : 'npm';
+};
+export const installCommand = (manager, hasNpmLockfile) => [
+    manager,
+    manager === 'npm' && hasNpmLockfile ? 'ci' : 'install',
+];
+export const developCommand = (manager) => [manager, 'run', 'develop'];
+export const quoteArgument = (value) => {
+    if (/^[\w@%+=:,./-]+$/u.test(value)) {
+        return value;
+    }
+    if (process.platform === 'win32') {
+        return `"${value.replaceAll('"', '\\"')}"`;
+    }
+    return `'${value.replaceAll("'", "'\\''")}'`;
+};
+export const displayCommand = (command) => command.map(quoteArgument).join(' ');

package/lib/project.js

@@ -0,0 +1,55 @@
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { UserError, errorCause } from './errors.js';
+export const packageName = (directory) => {
+    const name = basename(resolve(directory))
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/gu, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/gu, '-')
+        .replace(/^[._-]+|[._-]+$/gu, '')
+        .slice(0, 214);
+    if (!name) {
+        return 'my-ssr-app';
+    }
+    return ['node_modules', 'favicon.ico'].includes(name) ? `my-${name}` : name;
+};
+export const rewritePackage = (manifest, directory, git) => {
+    const result = {
+        ...manifest,
+        name: packageName(directory),
+        version: '0.1.0',
+    };
+    for (const key of ['description', 'repository', 'homepage', 'bugs', 'author', 'keywords']) {
+        delete result[key];
+    }
+    if (!git && result.scripts && typeof result.scripts === 'object') {
+        const scripts = { ...result.scripts };
+        delete scripts.prepare;
+        result.scripts = scripts;
+    }
+    return result;
+};
+export const postProcess = async (directory, nameFrom, git) => {
+    const manifestPath = join(directory, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new UserError(`Unable to read the template package.json: ${errorCause(error)}`);
+    }
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+        throw new UserError('The template package.json must contain a JSON object');
+    }
+    const rewritten = rewritePackage(manifest, nameFrom, git);
+    await writeFile(manifestPath, `${JSON.stringify(rewritten, null, 2)}\n`);
+    await removeTemplateMetadata(directory, git);
+};
+export const removeTemplateMetadata = async (directory, git) => {
+    const removals = ['.github', 'renovate.json', 'CHANGELOG.md', 'LICENSE', 'SECURITY.md'];
+    if (!git) {
+        removals.push('.husky');
+    }
+    await Promise.all(removals.map((file) => rm(join(directory, file), { recursive: true, force: true })));
+};

package/lib/source.js

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { gunzip } from 'node:zlib';
+import { UserError, errorCause } from './errors.js';
+import { copyDirectory, statIfExists } from './files.js';
+import { extractTar } from './tar.js';
+const decompress = promisify(gunzip);
+const archiveBase = 'https://codeload.github.com/Lomray-Software/vite-template/tar.gz';
+export const downloadArchive = async (ref, allowRefFallback) => {
+    const encodedRef = ref.split('/').map(encodeURIComponent).join('/');
+    const urls = [`${archiveBase}/refs/heads/${encodedRef}`];
+    if (allowRefFallback) {
+        urls.push(`${archiveBase}/${encodedRef}`);
+    }
+    for (const [index, url] of urls.entries()) {
+        let response;
+        try {
+            response = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+            if (response.ok) {
+                return Buffer.from(await response.arrayBuffer());
+            }
+        }
+        catch (error) {
+            throw new UserError(`Unable to download template ref "${ref}": network failure (${errorCause(error)})`);
+        }
+        await response.body?.cancel();
+        if (response.status !== 404 || index === urls.length - 1) {
+            throw new UserError(`Unable to download template ref "${ref}": HTTP ${response.status} ${response.statusText}`);
+        }
+    }
+    throw new UserError(`Template ref "${ref}" was not found`);
+};
+export const loadSource = async (destination, ref, allowRefFallback, source) => {
+    let compressed;
+    if (source) {
+        const path = resolve(source);
+        const info = await statIfExists(path);
+        if (!info || (!info.isDirectory() && !info.isFile())) {
+            throw new UserError(`Offline source "${path}" must be a .tar.gz file or directory`);
+        }
+        if (info.isDirectory()) {
+            await copyDirectory(path, destination);
+            return;
+        }
+        compressed = await readFile(path);
+    }
+    else {
+        compressed = await downloadArchive(ref, allowRefFallback);
+    }
+    let archive;
+    try {
+        archive = await decompress(compressed);
+    }
+    catch (error) {
+        throw new UserError(`Unable to decompress template archive: ${errorCause(error)}`);
+    }
+    await extractTar(archive, destination);
+};

package/lib/tar.js

@@ -0,0 +1,187 @@
+import { constants } from 'node:fs';
+import { chmod, mkdir, open, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { UserError } from './errors.js';
+import { statIfExists } from './files.js';
+const BLOCK_SIZE = 512;
+const readString = (buffer, start, length) => buffer
+    .subarray(start, start + length)
+    .toString('utf8')
+    .split('\0')[0] ?? '';
+const readNumber = (buffer, start, length) => {
+    const field = buffer.subarray(start, start + length);
+    if (field[0] & 0x80) {
+        let value = BigInt(field[0] & 0x7f);
+        for (const byte of field.subarray(1)) {
+            value = value * 256n + BigInt(byte);
+        }
+        if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new UserError('Invalid tar archive: numeric field is too large');
+        }
+        return Number(value);
+    }
+    const text = readString(buffer, start, length).trim();
+    if (text && !/^[0-7]+$/u.test(text)) {
+        throw new UserError('Invalid tar archive: expected an octal numeric field');
+    }
+    const value = Number.parseInt(text || '0', 8);
+    if (!Number.isSafeInteger(value)) {
+        throw new UserError('Invalid tar archive: numeric field is too large');
+    }
+    return value;
+};
+const checkHeader = (header) => {
+    let checksum = 0;
+    for (const [index, byte] of header.entries()) {
+        checksum += index >= 148 && index < 156 ? 32 : byte;
+    }
+    if (checksum !== readNumber(header, 148, 8)) {
+        throw new UserError('Invalid tar archive: header checksum does not match');
+    }
+};
+const parsePax = (data) => {
+    const fields = Object.create(null);
+    let offset = 0;
+    while (offset < data.length) {
+        const space = data.indexOf(32, offset);
+        const sizeText = data.subarray(offset, space).toString('ascii');
+        const size = Number(sizeText);
+        if (space < offset ||
+            !/^\d+$/u.test(sizeText) ||
+            !Number.isSafeInteger(size) ||
+            size <= space - offset + 1 ||
+            offset + size > data.length ||
+            data[offset + size - 1] !== 10) {
+            throw new UserError('Invalid tar archive: malformed pax record');
+        }
+        const record = data.subarray(space + 1, offset + size - 1).toString('utf8');
+        const equals = record.indexOf('=');
+        if (equals < 1) {
+            throw new UserError('Invalid tar archive: malformed pax attribute');
+        }
+        fields[record.slice(0, equals)] = record.slice(equals + 1);
+        offset += size;
+    }
+    return fields;
+};
+export const entryPath = (root, name) => {
+    if (name.includes('\\') ||
+        name.includes('\0') ||
+        name.startsWith('/') ||
+        /^[a-z]:/iu.test(name)) {
+        throw new UserError(`Unsafe tar entry "${name}": path escapes the target directory`);
+    }
+    const components = name.split('/').filter((component) => component && component !== '.');
+    if (components.includes('..')) {
+        throw new UserError(`Unsafe tar entry "${name}": path escapes the target directory`);
+    }
+    components.shift();
+    if (components.length === 0 || components.includes('.git')) {
+        return undefined;
+    }
+    const destination = resolve(root, ...components);
+    const withinRoot = relative(resolve(root), destination);
+    if (withinRoot === '..' || withinRoot.startsWith(`..${sep}`) || isAbsolute(withinRoot)) {
+        throw new UserError(`Unsafe tar entry "${name}": path escapes the target directory`);
+    }
+    return destination;
+};
+const ensureDirectory = async (root, directory) => {
+    const parts = relative(root, directory).split(sep).filter(Boolean);
+    let current = root;
+    for (const part of ['', ...parts]) {
+        current = join(current, part);
+        const info = await statIfExists(current);
+        if (info && (!info.isDirectory() || info.isSymbolicLink())) {
+            throw new UserError(`Unsafe tar destination "${current}": expected a directory without symlinks`);
+        }
+        await mkdir(current, { recursive: true });
+    }
+};
+/** Read ustar, pax and GNU long-name archives, stripping their enclosing directory. */
+export const extractTar = async (archive, directory) => {
+    const root = resolve(directory);
+    const directoryModes = new Map();
+    let pax = {};
+    let longName;
+    let offset = 0;
+    let hasEnded = false;
+    await ensureDirectory(root, root);
+    while (offset + BLOCK_SIZE <= archive.length) {
+        const header = archive.subarray(offset, offset + BLOCK_SIZE);
+        if (header.every((byte) => byte === 0)) {
+            hasEnded = true;
+            break;
+        }
+        checkHeader(header);
+        const type = readString(header, 156, 1);
+        const isExtended = ['x', 'g', 'L', 'K'].includes(type);
+        const headerSize = readNumber(header, 124, 12);
+        const size = !isExtended && pax.size !== undefined ? Number(pax.size) : headerSize;
+        if (!Number.isSafeInteger(size) || size < 0) {
+            throw new UserError('Invalid tar archive: invalid entry size');
+        }
+        const start = offset + BLOCK_SIZE;
+        const next = start + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+        if (next > archive.length) {
+            throw new UserError('Invalid tar archive: truncated entry');
+        }
+        const data = archive.subarray(start, start + size);
+        offset = next;
+        if (type === 'g') {
+            // GitHub emits pax_global_header with repository metadata, not project files.
+            continue;
+        }
+        if (type === 'x') {
+            pax = { ...pax, ...parsePax(data) };
+            continue;
+        }
+        if (type === 'L') {
+            longName = readString(data, 0, data.length);
+            continue;
+        }
+        if (type === 'K') {
+            continue;
+        }
+        const prefix = readString(header, 257, 6) === 'ustar' ? readString(header, 345, 155) : '';
+        const headerName = [prefix, readString(header, 0, 100)].filter(Boolean).join('/');
+        const name = pax.path ?? longName ?? headerName;
+        pax = {};
+        longName = undefined;
+        // Skip links, devices, FIFOs and other non-file entries without following them.
+        if (!['', '0', '5'].includes(type) || name === 'pax_global_header') {
+            continue;
+        }
+        const destination = entryPath(root, name);
+        if (!destination) {
+            continue;
+        }
+        const mode = readNumber(header, 100, 8) & 0o777;
+        if (type === '5' || name.endsWith('/')) {
+            await ensureDirectory(root, destination);
+            directoryModes.set(destination, mode);
+            continue;
+        }
+        await ensureDirectory(root, dirname(destination));
+        const existing = await statIfExists(destination);
+        if (existing && (!existing.isFile() || existing.isSymbolicLink())) {
+            throw new UserError(`Unsafe tar destination "${destination}": expected a regular file`);
+        }
+        await rm(destination, { force: true });
+        const file = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, mode);
+        try {
+            await file.writeFile(data);
+            await file.chmod(mode);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    if (!hasEnded) {
+        throw new UserError('Invalid tar archive: missing end-of-archive block');
+    }
+    const deepestFirst = [...directoryModes].sort(([left], [right]) => right.length - left.length);
+    for (const [path, mode] of deepestFirst) {
+        await chmod(path, mode);
+    }
+};

package/lib/templates.js

@@ -0,0 +1,19 @@
+export const templates = {
+    full: {
+        branch: 'prod',
+        description: 'Streaming SSR, MobX, consistent Suspense, meta tags and route management',
+    },
+    minimal: {
+        branch: 'example/minimal',
+        description: 'Six runtime dependencies, loaders, a lazy route with CSS, redirect, client-only route and 404, plus the SPA-to-SSR file diff',
+    },
+    'custom-server': {
+        branch: 'example/custom-server',
+        description: 'Development through the managed CLI, production through an application-owned Fastify server with static assets, compression and Early Hints; dual export of the managed entry and a Fetch handler',
+    },
+    localization: {
+        branch: 'example/localization',
+        description: 'i18next with the language chosen on the server from the cookie or Accept-Language, transferred to the client before hydration, and a cookie-based switcher',
+    },
+};
+export const isTemplate = (value) => Object.hasOwn(templates, value);

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@lomray/create-ssr-app",
+  "version": "1.0.0",
+  "description": "Create a Lomray Vite SSR application from the official templates.",
+  "type": "module",
+  "bin": {
+    "create-ssr-app": "bin/create-ssr-app.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lomray-Software/create-ssr-app.git"
+  },
+  "homepage": "https://github.com/Lomray-Software/create-ssr-app",
+  "bugs": {
+    "url": "https://github.com/Lomray-Software/create-ssr-app/issues"
+  },
+  "keywords": [
+    "vite",
+    "ssr",
+    "react",
+    "scaffold",
+    "create",
+    "lomray"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint:check": "eslint . --max-warnings=0 && prettier --check .",
+    "lint:format": "eslint . --fix && prettier --write .",
+    "ts:check": "tsc --noEmit",
+    "test": "vitest run --exclude tests/e2e.test.ts",
+    "test:e2e": "npm run build && vitest run tests/e2e.test.ts --reporter=verbose",
+    "prepare": "husky",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@lomray/eslint-config": "^7.0.0",
+    "@lomray/prettier-config": "^3.0.0",
+    "@types/node": "^22.20.1",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.9.6",
+    "semantic-release": "^25.0.9",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.69.0",
+    "vitest": "^5.0.0"
+  }
+}