Skip to content

Latest commit

 

History

History
135 lines (95 loc) · 7.81 KB

Options.md

File metadata and controls

135 lines (95 loc) · 7.81 KB

Options

All three of create-typescript-app's setup scripts -creation, initialization, and migration- support a shared set of input options.

This page uses npx create-typescript-app in its code examples, but pnpm run initialize works the same.

Required Options

The following required options will be prompted for interactively if not provided as CLI flags.

Base and Mode

These required options determine how the creation script will set up and scaffold the repository:

  • --base: Whether to scaffold the repository with:
    • everything that comes with the template (recommended)
    • minimum amounts of tooling, essentially opting out of everything
    • prompt for which portions to exclude
  • --create-repository (boolean): Whether to create a corresponding repository on github.com (if it doesn't yet exist)
  • --mode: Whether to:
    • create a new repository in a child directory
    • initialize a freshly repository in the current directory
    • migrate an existing repository in the current directory

For example, scaffolding a full new repository in the current directory and also linking it to a new repository on github.com:

npx create-typescript-app --base everything --create-repository --mode create

Core Options

These required options determine the options that will be substituted into the template's files:

  • --description (string): Sentence case description of the repository (e.g. Quickstart-friendly TypeScript package with lots of great repository tooling. ✨)
  • --owner (string): GitHub organization or user the repository is underneath (e.g. JoshuaKGoldberg)
  • --repository (string): The kebab-case name of the repository (e.g. create-typescript-app)
  • --title (string): Title Case title for the repository to be used in documentation (e.g. Create TypeScript App)

For example, pre-populating all core required options and also creating a new repository:

npx create-typescript-app --create-repository --base everything --mode create --repository testing-repository --title "Testing Title" --owner TestingOwner --description "Test Description"

That script will run completely autonomously, no prompted inputs required. ✨

Optional Options

The setup scripts also allow for optional overrides of the following inputs whose defaults are based on other options:

  • --access ("public" | "restricted): Which npm publish --access to release npm packages with (by default, "public")
  • --author (string): Username on npm to publish packages under (by default, an existing npm author, or the currently logged in npm user, or owner.toLowerCase())
  • --email (string): Email address to be listed as the point of contact in docs and packages (e.g. [email protected])
    • Optionally, --email-github (string) and/or --email-npm (string) may be provided to use different emails in .md files and package.json, respectively
  • --funding (string): GitHub organization or username to mention in funding.yml (by default, owner)
  • --logo (string): Local image file in the repository to display near the top of the README.md as a logo
    • --logo-alt (string): If --logo is provided or detected from an existing README.md, alt text that describes the image will be prompted for if not provided

For example, customizing the ownership and users associated with a new repository:

npx create-typescript-app --author my-npm-username --email [email protected] --funding MyGitHubOrganization

💡 You can always manually edit files such as package.json after running a setup script.

Opt-Outs

The setup scripts can be directed with CLI flags to opt out tooling portions and/or using API calls.

Excluding Tooling Portions

The setup scripts normally will prompt you to select how much of the tooling you'd like to enable in a new repository. Alternately, you can bypass that prompt by providing any number of the following CLI flags:

  • --exclude-all-contributors: Don't add all-contributors to track contributions and display them in a README.md table.
  • --exclude-compliance: Don't add a GitHub Actions workflow to verify that PRs match an expected format.
  • --exclude-lint-json: Don't apply linting and sorting to *.json and *.jsonc files.
  • --exclude-lint-knip: Don't add Knip to detect unused files, dependencies, and code exports.
  • --exclude-lint-md: Don't apply linting to *.md files.
  • --exclude-lint-package-json: Don't add npm-package-json-lint to lint for package.json correctness.
  • --exclude-lint-deprecation: Don't use eslint-plugin-deprecation to report on usage of code marked as @deprecated.
  • --exclude-lint-eslint: Don't use eslint-plugin-eslint-comment to enforce good practices around ESLint comment directives.
  • --exclude-lint-jsdoc: Don't use eslint-plugin-jsdoc to enforce good practices around JSDoc comments.
  • --exclude-lint-packages: Don't add a pnpm dedupe workflow to ensure packages aren't duplicated unnecessarily.
  • --exclude-lint-perfectionist: Don't apply eslint-plugin-perfectionist to ensure imports, keys, and so on are in sorted order.
  • --exclude-lint-regex: Don't add eslint-plugin-regex to enforce good practices around regular expressions.
  • --exclude-lint-strict: Don't augment the recommended logical lint rules with typescript-eslint's strict config.
  • --exclude-lint-stylistic: Don't add stylistic rules such as typescript-eslint's stylistic config.
  • --exclude-lint-spelling: Don't add cspell to spell check against dictionaries of known words.
  • --exclude-lint-yml: Don't apply linting and sorting to *.yaml and *.yml files.
  • --exclude-releases: Don't add release-it to generate changelogs, package bumps, and publishes based on conventional commits.
  • --exclude-renovate: Don't add a Renovate config to dependencies up-to-date with PRs.
  • --exclude-tests: Don't add Vitest tooling for fast unit tests, configured with coverage tracking.

For example, initializing with all tooling except for package.json checks and Renovate:

npx create-typescript-app --exclude-lint-package-json --exclude-lint-packages --exclude-renovate

Warning Specifying any --exclude-* flag on the command-line will cause the setup script to skip prompting for more excludes.

Skipping API Calls

You can prevent the migration script from making some network-based changes using any or all of the following CLI flags:

  • --skip-all-contributors-api (boolean): Skips network calls that fetch all-contributors data from GitHub
    • This flag does nothing if --skip-all-contributors was specified.
  • --skip-github-api (boolean): Skips calling to GitHub APIs.
  • --skip-install (boolean): Skips installing all the new template packages with pnpm.

For example, providing all three flags will completely skip all network requests:

npx create-typescript-app --skip-all-contributors-api --skip-github-api --skip-install

💡 Tip: To temporarily preview what the script would apply without making changes on GitHub, you can run with all --skip-*-api flags, then git add -A; git reset --hard HEAD to completely reset all changes.

Skipping Local Changes

You can prevent the migration script from making some changes on disk using any or all of the following CLI flags:

  • --skip-removal (boolean): Skips removing setup docs and scripts, including this docs/ directory
  • --skip-restore (boolean): Skips the prompt offering to restore the repository if an error occurs during setup
  • --skip-uninstall (boolean): Skips uninstalling packages only used for setup scripts

For example, providing all local change skip flags:

npx create-typescript-app --skip-removal --skip-restore --skip-uninstall