FAQs

Consumption

How do I use create?

For now, you don’t. It’s still very early stage.

Soon, there will be APIs added and documented that allow providing a Preset and having the create engine create a new repository or update an existing one based on it.

npx create (or something similar) will be able to take in a package containing a Preset and run with it. For example, using a Preset soon to be provided by create-typescript-app:

npx create typescript-app

Later, there will be higher-level scaffolding utilities that will allow packages such as create-typescript-app to:

• Generate full documentation websites to describe their Blocks and Presets
• Manage and keep updated sample repositories for their presets
• Migrate repositories from external tools and/or older Preset or Template versions

See JoshuaKGoldberg/create-typescript-app#1181 📝 Documentation: Long-term project vision for more history.

Will there be GitHub repository template support akin to create-typescript-app’s?

Yes, after the create and update APIs are done.

Will there be repository migration akin to create-typescript-app’s?

Yes, after the create and update APIs are done.

Development

Why can’t we define Args for Blocks in Presets?

In other words, you might be wondering why the API doesn’t allow something like this:

export const presetExample = base.createPreset({
  blocks: [
    myBlock({
      someArg: "...",
    }),
  ],
});

This is because Blocks shouldn’t need to be configured. Users should be able to turn them off and on at will without any configuration.

Passing Args to a Block in a Preset means users will have no way to override or remove those Args.

Why do some testers allow take and others the individual system pieces?

It depends on what APIs the entities under test conceptually use.

Entity	Mock	Why
Bases	take	Bases should go through Inputs to interact with the system.
Blocks	Neither	Blocks should be synchronous and take any input values from their Base Options.
Inputs	Both	Inputs receive system pieces, and can also take other Inputs.
Presets	System	High-level users of Presets should not care about low-level implementation details of Inputs.

Tool Comparisons

create is targeting being a fully complete solution for defining creating, migrating, and/or updating repositories to use flexible templates. Those templates are defined in a feature-by-feature (“Block”) basis and with configurable “Presets” using create APIs. create templates go beyond just file system copying with network requests, shell commands, and versioned migrations.

Other ecosystem tools exist for part of that feature set. None target the full feature set of create.

In general, create’s approach is differentiated from previous projects by:

• Producing outputs -including files and more- in a generalized format (Direct Creations)
• Allowing sub-templates that can be individually swapped individually and add to each other (Blocks)

Danger

Most of these project comparisons have not yet been vetted by maintainers on the projects. They might be wildly inaccurate.

create-next-app, create-react-app, create-typescript-app, etc

create is an engine that allows you to define repository templates. It itself is not a repository template; it instead provides APIs that you can use to build your own repository template.

In other words, create is a lower-level primitive that can be used to create higher-level create-*-app templates.

Note

For more history on how create came to be, see JoshuaKGoldberg/create-typescript-app#1181 📝 Documentation: Long-term project vision.

Cookiecutter

Cookiecutter is a library and CLI app for generating projects from templates. It allows taking in directories written as Jinja templates and running pre- and post-generation hooks.

create has several key differences from what Cookiecutter supports:

• Cookiecutter is a wrapper around a Jinja file templates; create allows for full JavaScript logic to generate contents based on provided options
• Cookiecutter always operates at the scale of one template; create provides more granular APIs for areas of features (Blocks and Presets)
• Cookiecutter supports file changes; create additionally supports network calls and arbitrary shell scripts as outputs

Cookiecutter is also written in Python and is installed using tools in the Python ecosystem. create is written in TypeScript and is set up to work in the web ecosystem.

copier

Copier is a library and CLI app for generating projects from templates. It takes in a local path or Git URL and dynamically replaces values in text files.

create has several key additions on top of what Copier supports:

• Copier is a wrapper around a straightforward file templates; create allows for dynamic logic for generating contents based on provided options
• Copier only supports file templates; create allows for sending network requests and running shell scripts
• Copier always operates at the scale of one template; create provides more granular APIs for areas of features (Blocks and Presets)

Copier is also written in Python and is installed using tools in the Python ecosystem. create is written in TypeScript and is set up to work in the web ecosystem.

degit

degit is a tool that makes copies Git of repositories. It allows for straightforward initialization of files, along with support for post-creation actions.

create has several key additions on top of what degit supports:

• degit is a wrapper around a straightforward git clone; create allows for dynamic logic for generating contents based on provided options
• degit only supports limited post-clone actions; create allows for sending network requests and running shell scripts
• degit always operates at the scale of a full repository; create provides more granular APIs for areas of features (Blocks and Presets)

GitHub Template Repositories

GitHub Template Repositories are a GitHub feature allowing making a new repository as a clone of another. Created repositories appear on github.com with a generated from … notice.

create will include treating sources as templates, and additionally adds features:

• Template Repositories are a wrapper around a straightforward git clone; create allows for changing generated file contents based on provided options
• Template Repositories don’t support post-clone actions; create allows for sending network requests and running shell scripts
• Template Repositories always operate at the scale of a full repository; create provides more granular APIs for areas of features (Blocks and Presets)

Hygen

Hygen is web ecosystem tool for defining generators to automate common file system tasks. It encourages building your own generators that include templates built with the EJS embedded JavaScript templating engine. Hygen templates can have conditional rendering, embedded JavaScript, and injected shell scripts.

create takes a different architectural approach than Hygen:

• Hygen templates are imperative descriptions of files and frontmatter; create groups areas into blocks
• Hygen templates heavily build on EJS and do not have type-safe options; create has options explicitly defined with Zod schemas
• create Blocks describe their own outputs and additions to other Blocks, allowing them to be individually toggled

Plop

Plop is web ecosystem tool for defining repository templates. Like create, it allows defining templates for generated files.

create has several key differences from Plop:

• Plop is built around an imperative “actions” API for adding files, as opposed to create’s managing of outputs
• Plop only supports file creation, not other actions such as setting repository GitHub systems
• Plop is built on the popular Inquirer.js and Handlebars libraries, rather than create’s more type-safe Zod schema options

In other words, create is a more broadly scoped project for full repository generation, whereas Plop is more finely targeted to applying Handlebars templates.

projen

projen is web ecosystem tool for defining repository templates. It is similar to create in that it is a flexible underlying engine that allows developers define and manage project configurations through code.

create has several large differences from projen:

• create is a generalized, tooling-agnostic generator engine that can also keep repositories updated over time
• projen generally targets tighter integration and management with created projects, including being used in its package scripts

More details on create differing from projen

• Ecosystem targets:
  • create only includes packages in JavaScript/TypeScript; it only targets support for the web ecosystem.
  • projen includes packages in Go, Java, JavaScript/TypeScript, and Python; it can be generally used for those ecosystems.
• Integration with generated repositories:
  • create does not add any tooling to generated repositories; it prioritizes inferring options from existing repositories on demand.
  • projen is used in generated repositories and integrates with the repository’s tasks.
• Integration with ecosystem tooling:
  • create does not hardcode types of tasks or the tools used for them.
  • projen bundles its own understanding of ecosystem tools such as package managers and linters, and provides APIs for projects to choose from its preferred tools.
• Low-level code design principles:
  • create uses lean functions. Output file structures are defined with raw objects and strings.
  • projen leans into classes in its architecture. It heavily uses jsii and defines output files with classes.

Note

For more details on how create compares to Projen, see JoshuaKGoldberg/create-typescript-app#1181 📝 Documentation: Long-term project vision#issuecomment-2428303689

Yeoman

Yeoman is a much older tool in the web ecosystem for templating. Its architecture and APIs generally work with older, now-outdated JavaScript practices:

• Project generators must extend yeoman-generator’s Generator and define methods that are dynamically discovered and called at runtime
• System interactions such as installing dependencies and writing files are done by imperatively calling Yeoman APIs, as opposed to producing outputs that are managed by create
• Persistent options are provided in a raw .yo-rc.json JSON file rather than type-safe schema definitions

Yeoman has not been actively maintained in several years.