neew turns remote generator repositories into reusable commands. Register a
repository once, invoke its generators by name from any directory, and let a
small fetch engine reuse a local cache until the remote ref actually moves.
Start with docs/getting-started.md, then read the module for the domain you need:
- generator-repository.md: the repository contract
- repository-registry.md: registering, removing, listing, collisions
- source-fetching.md: links, change detection, caching, offline use
- generator-invocation.md: running generators, parameters, targets
pnpm add -g @trut/neewAny Git repository becomes a neew generator repository by adding a single
barrel file, generators.ts, at its root. The barrel default-exports a
generators array of paths or glob patterns resolved relative to the repository
root. Author it with the defineGenerators helper exported by this package:
import { defineGenerators } from '@trut/neew';
export default defineGenerators({
generators: ['./generators/*.generator.ts'],
});Each pattern must match at least one generator module. A module declares a
@trut/gen generator with a unique name, an optional description, and the
prompts that become the parameters neew accepts. For example
generators/component.generator.ts:
import { addTemplates, defineGenerator, text } from '@trut/gen';
export default defineGenerator({
name: 'component',
description: 'Create a component',
basePath: 'src',
prompts: {
name: text({ message: 'Component name', placeholder: 'UserProfile' }),
},
actions: [
addTemplates({
from: 'templates/component',
to: 'components/<%= it.format.kebabCase(it.answers.name) %>',
}),
],
});Generator names must be unique within the repository; two resolved generators sharing a name fail resolution.
Generators may use custom @trut/gen actions by declaring a separate runtime
handler module. The barrel holds only its path, so neew does not initialize the
module while registering the repository or displaying help:
import { defineGenerators } from '@trut/neew';
export default defineGenerators({
generators: ['./generators/*.generator.ts'],
runtime: { handlers: './runtime/handlers.ts' },
});The handler module default-exports a registry. Define action shapes in the generator repository, namespace their types, and keep any integration-specific dependencies there:
import { defineRuntimeHandlers } from '@trut/neew';
import { stageFile } from '@trut/gen/runtime';
declare module '@trut/gen' {
interface GenActions {
'acme/manifest': { readonly type: 'acme/manifest'; readonly name: string };
}
}
export default defineRuntimeHandlers({
'acme/manifest': async (action, context) => {
const manifest = await createManifest(action.name);
context.answers.manifest = manifest;
stageFile(context, `${context.basePath}/manifest.json`, JSON.stringify(manifest));
},
});Neew loads this module only for an actual generator run and passes the registry
to @trut/gen. A rejected handler aborts the run before Gen commits staged
files.
A generator that initializes a project can keep ordinary, ready-to-use text
files and replace its embedded project identity at generation time. Export the
name present in those files and expose the target name through a projectName
prompt:
import { addTemplates, defineGenerator, text } from '@trut/gen';
export const projectName = 'Template Name';
export default defineGenerator({
name: 'project',
basePath: '.',
prompts: {
projectName: text({ message: 'Project name' }),
},
actions: [
addTemplates({
from: 'templates/project',
to: '<%= it.format.kebabCase(it.answers.projectName) %>',
}),
],
});Neew replaces title, Pascal, camel, kebab, snake, and constant forms of the exported name in supported text files. Output paths remain Gen's responsibility: use its normal path placeholders and dynamic action strings. Files outside the text-file allowlist are copied unchanged; generators without the export retain the default Eta behavior.
neew add <link> # register a repository and index its generators
neew remove <link> # unregister a repository and drop its cache
neew list # list repositories and their generators (offline)
neew create <generator> [options] # run a generator
neew <generator> [options] # shortcut for create
neew <generator> --help # list a generator's parameters
neew # list the commands and available generatorsOptions:
--target <dir>: write generated files into<dir>instead of the current directory.--dry-run: report the files that would be written without writing them.--force: replace existing files that collide with generated output.-h, --help,-v, --version.
Every generator prompt is exposed as a CLI flag (for example a name prompt
becomes --name). Missing values are prompted interactively on a TTY and fail
otherwise. The state lives in ~/.config/neew/neew.json (registry) and
~/.cache/neew/** (fetched repositories).