@turbo/gen and turbo generate

Purpose and Scope

The generator surface in Turborepo has two closely related audiences. Application teams use the command-line workflow to add new apps and packages to an existing workspace, while platform or tooling teams write repository-specific generators that encode local conventions. The reference docs present this as the way to extend a Turborepo with new apps and packages, and they split the command into a custom-generator path and a workspace-scaffolding path. The package docs then narrow the package responsibility to type definitions for generator authors, especially when writing generator configuration in TypeScript.

Sources: apps/docs/content/docs/reference/generate.mdx, apps/docs/content/docs/reference/turbo-gen.mdx, packages/turbo-gen/README.md

Use this page when you need a concise reference for the command names, flags, aliases, type imports, and runtime data available to generator actions. It is intentionally different from a conceptual guide: it does not teach every design pattern for building a generator, but it does explain how the public docs map onto the package entry point. The practical model is that the documented Turborepo command gives users a stable interface, while the generator package supplies the implementation-facing type surface and command behavior used to run custom or built-in scaffolding flows.

Sources: apps/docs/content/docs/reference/generate.mdx, packages/turbo-gen/src/cli.ts

Relevant Source Files

• apps/docs/content/docs/reference/generate.mdx - Documents the public turbo generate command, the turbo gen alias, the default run behavior, and the flags for run and workspace subcommands.
• apps/docs/content/docs/reference/turbo-gen.mdx - Documents the @turbo/gen package, the PlopTypes import pattern, and the injected turbo object available to generator actions.
• packages/turbo-gen/README.md - Provides the package-level installation and usage example for adding @turbo/gen as a development dependency and importing generator types.
• packages/turbo-gen/src/cli.ts - Wires the @turbo/gen CLI with commander, command aliases, option definitions, proxy support, update notifications, hidden raw command behavior, and error handling.

Command Surface

The primary documented entry point is the generate command. Running it with no additional subcommand is presented as the starting point for extending a repository, and the docs explicitly list two command families: one for running custom generators defined in the repository and another for creating a workspace. The shorthand gen is an alias for generate, and run is the default subcommand, so the short form can be used as the common entry for invoking a custom generator. This matters for automation because teams can standardize on the long form in docs while still allowing experienced maintainers to use the shorter command interactively.

turbo generate
turbo generate run [generator-name]
turbo gen run [generator-name]
turbo gen workspace [options]

Sources: apps/docs/content/docs/reference/generate.mdx

The run subcommand is for repository-defined generators rather than for generic workspace copying. It accepts an optional generator name, which allows an interactive selection flow when no name is supplied and a direct execution flow when the caller already knows the generator. Its documented flags cover three needs: passing answers directly to prompts, choosing the generator configuration file, and choosing the repository root. The default configuration file is the conventional generator config under the turbo generators directory, and the default root is discovered from the directory containing the root Turborepo configuration. Those defaults are useful because most repositories can add a conventional generator without requiring every caller to remember paths.

Sources: apps/docs/content/docs/reference/generate.mdx

Workspace Scaffolding Reference

The workspace subcommand creates a new package or app and is the command family to use when the goal is structural scaffolding rather than running an arbitrary custom generator. The name flag supplies the package name that will be written into the new workspace package metadata, which makes it the unique identifier inside the monorepo. Destination controls where files are created, and type narrows the workspace category to an app or package. The command also supports a root option so callers can run scaffolding from outside the repository root while still targeting the correct Turborepo project.

Sources: apps/docs/content/docs/reference/generate.mdx, packages/turbo-gen/src/cli.ts

The empty and copy modes are intentionally mutually exclusive in the implementation. Empty generation is the default path for creating a minimal workspace, while copy generation can use either a local workspace name inside the monorepo or a fully qualified GitHub URL. The CLI option definition marks empty as conflicting with copy and copy as conflicting with empty, preventing ambiguous instructions about whether to synthesize new files or clone an existing template. For GitHub templates, the example path flag handles the unusual but important case where a branch name contains a slash and the subdirectory path would otherwise be hard to parse.

turbo gen workspace --name @acme/ui --type package --destination packages/ui
turbo gen workspace --name web --type app --copy examples/next --destination apps/web
turbo gen workspace --copy https://github.com/acme/templates/tree/bug/fix-1 --example-path apps/web

Sources: apps/docs/content/docs/reference/generate.mdx, packages/turbo-gen/src/cli.ts

Dependency selection has a specific escape hatch. The show-all-dependencies flag prevents filtering available dependencies by workspace type when selecting dependencies to add. This is useful for repositories whose app and package categories do not align with the default expectation, or for platform repositories that intentionally share dependencies across categories. The flag should be used deliberately because the normal filtering behavior helps guide users toward dependencies that fit the chosen workspace type. In other words, the option trades guardrails for flexibility, and it belongs in documented team workflows only when the broader dependency model is already understood.

Sources: apps/docs/content/docs/reference/generate.mdx, packages/turbo-gen/src/cli.ts

@turbo/gen Types and Generator Context

Generator authors use the package for type definitions. The documented pattern imports PlopTypes from the package and exports a default function that receives a NodePlopAPI object. Inside that function, authors call the generator registration API, provide a human-readable name and description, define prompts that gather user input, and define actions that perform file changes based on those answers. The package README repeats the same installation-oriented usage flow, showing that the package is meant to be installed as a development dependency and used from a generator configuration file.

pnpm add @turbo/gen --save-dev

import type { PlopTypes } from "@turbo/gen";
 
export default function generator(plop: PlopTypes.NodePlopAPI): void {
  plop.setGenerator("Generator name", {
    description: "Generator description",
    prompts: [],
    actions: []
  });
}

Sources: apps/docs/content/docs/reference/turbo-gen.mdx, packages/turbo-gen/README.md

When generator actions run, Turborepo injects a turbo object into the answers data. The paths section tells an action where it was invoked, where the project root is, and, when applicable, which workspace contains the generator. The workspace path may be undefined for a root-level generator, so generator code should treat it as optional rather than assuming every generator lives inside a package. This context is especially valuable for templates that need to compute relative destinations, update files near the root, or behave differently when a package-level generator is invoked from within a workspace.

Sources: apps/docs/content/docs/reference/turbo-gen.mdx

The same injected object includes a configs array containing parsed Turborepo configuration files discovered in the repository. Each entry carries the parsed configuration object, the absolute path to the Turborepo config file, the absolute workspace path containing that config, and a boolean that identifies whether it is the root config. This is more than metadata: it lets a generator inspect whether a task already exists before adding files, locate package-level configuration, or avoid overwriting root-level decisions. Generators that modify tasks should use this context rather than assuming a single root-only configuration shape.

Sources: apps/docs/content/docs/reference/turbo-gen.mdx

CLI Implementation Details

The package CLI is implemented with commander and names itself as the @turbo/gen command while describing its purpose as extending a Turborepo. It registers version and help options, creates an update notification helper from package metadata, and installs a proxy agent as the global HTTP and HTTPS agent so common proxy environment variables can be honored for network operations. Those details are implementation-oriented, but they explain why workspace copying from remote sources can participate in enterprise proxy setups and why users may see update notifications after command completion.

Sources: packages/turbo-gen/src/cli.ts

The implementation mirrors the documented command surface but adds a few operational details. The run command is the default and has the short alias r. The workspace command has the alias w. The args option on run defaults to an empty array, which gives command handlers a consistent shape even when no direct answers are provided. The workspace type option restricts values to app and package, aligning the command parser with the public reference. The hidden raw command accepts a type and raw JSON arguments, which signals an internal or lower-level execution path without adding it to the normal user-facing reference.

Sources: packages/turbo-gen/src/cli.ts

Error handling is designed to keep interactive use clean while still reporting real failures. If the prompt layer raises an ExitPromptError, the process exits silently, matching the common expectation that pressing control C should not print a stack trace. If a failure is a GeneratorError, the CLI prints the error message as a user-facing generator problem. Other errors are reported as unexpected and include the error object, asking the user to report the issue as a bug. The update notification helper is also awaited on failure with an error status, so the command can complete its notification behavior consistently.

Sources: packages/turbo-gen/src/cli.ts

Practical Usage Guidance

For a team introducing generators, start with the simplest separation of responsibilities. Use workspace generation for repeatable package or app creation, especially when copying a known workspace shape or creating an empty package at a chosen destination. Use a custom run generator when the flow needs prompts, conditional actions, or repository-specific edits that go beyond file copying. Install the types package for TypeScript generator configuration, define clear generator names and descriptions, and use the injected paths and configs data to make the generator location-aware rather than hard-coding assumptions about the repository layout.

Sources: apps/docs/content/docs/reference/generate.mdx, apps/docs/content/docs/reference/turbo-gen.mdx, packages/turbo-gen/README.md

When documenting local generator workflows, include both the long command and any preferred shorthand, the expected root, and whether arguments are supplied interactively or through the args option. For workspace templates, record whether the source is a local workspace or a GitHub URL, and document the example path separately if branch names may contain slashes. Good generator documentation should also describe what files are changed, which Turborepo configs may be updated, and how a user can safely review the generated diff before committing. Next, read the generating-code guide for design patterns and the configuration reference when a generator needs to create or update task definitions.

Sources: apps/docs/content/docs/reference/generate.mdx, apps/docs/content/docs/reference/turbo-gen.mdx