Skip to content

Latest commit

 

History

History
125 lines (85 loc) · 6.6 KB

Options.md

File metadata and controls

125 lines (85 loc) · 6.6 KB

Options

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

This page uses npx template-typescript-node-package 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 template-typescript-node-package --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. A 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. template-typescript-node-package)
  • --title (string): Title Case title for the repository to be used in documentation (e.g. Template TypeScript Node Package)

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

npx template-typescript-node-package --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:

  • --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])
  • --funding (string): GitHub organization or username to mention in funding.yml (by default, owner)

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

npx template-typescript-node-package --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-compliance: Don't add a GitHub Actions workflow to verify that PRs match an expected format.
  • --exclude-contributors: Don't add all-contributors to track contributions and display them in a README.md table.
  • --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-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-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 template-typescript-node-package --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-contributors-data (boolean): Skips network calls that fetch all-contributors data from GitHub
    • This flag does nothing if --exclude-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 template-typescript-node-package --skip-contributors-data --skip-github-api --skip-install

💡 Tip: To temporarily preview what the script would apply, you can run with all --skip-* 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 template-typescript-node-package --skip-removal --skip-restore --skip-uninstall