Skip to content

Commit 20ab241

Browse files
JoshuaKGoldbergJoshuaKGoldberg
authored
docs: replace 'Options.md' with 'CLI.md' and 'Configuration Files.md' (#1986)
## PR Checklist - [x] Addresses an existing open issue: fixes #1124 - [x] That issue was marked as [`status: accepting prs`](https://github.com/JoshuaKGoldberg/create-typescript-app/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) - [x] Steps in [CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/create-typescript-app/blob/main/.github/CONTRIBUTING.md) were taken ## Overview Splits the existing `Options.md` into two docs: * `CLI.md`: describing the common case of running `npx create-typescript-app` * `Configuration Files.md`: describing the less-common case of using a `create-typescript-app.config.js` Includes tests that each option is mentioned between the two of them. 🎁
1 parent 907fe76 commit 20ab241

17 files changed

+333
-152
lines changed

‎README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,8 @@ You can read more about the supported runtime modes in their docs pages:
4848
You can read more about `create-typescript-app` and the tooling it supports:
4949

5050
1. [**Blocks**](./docs/Blocks.md): a breakdown of all the pieces this template can set up.
51-
2. [**Options**](./docs/Options.md): granular options to customize how the template is run.
52-
3. [**FAQs**](./docs/FAQs.md): frequently asked questions
51+
2. [**CLI**](./docs/CLI.md): providing granular options to customize how the template is run.
52+
3. [**FAQs**](./docs/FAQs.md): frequently asked questions and troubleshooting
5353

5454
> [!NOTE]
5555
> This template is early stage, opinionated, and not endorsed by the TypeScript team.

‎cspell.json

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
"words": [
1313
"Anson",
1414
"apexskier",
15+
"attw",
1516
"automerge",
1617
"dbaeumer",
1718
"infile",

‎docs/Blocks.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ This table summarizes each block and which base levels they're included in:
5151
| Vitest | `--exclude-vitest` | | ✅ | 💯 |
5252
| VS Code | `--exclude-vs-code` | | | 💯 |
5353

54-
See also [Options](./Options.md) for how to customize the way template is run.
54+
See also [CLI](./CLI.md) for customizing templated repositories when running `npx create-typescript-app`.
5555

5656
## "Minimal" Base Level
5757

‎docs/CLI.md

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# CLI
2+
3+
`create-typescript-app` supports all the flags supported by [Bingo CLI](https://www.create.bingo/cli)s.
4+
It also provides a collection of custom flags per [Bingo CLI > Template Flags](https://www.create.bingo/cli#template-flags).
5+
6+
```shell
7+
npx create-typescript-app
8+
```
9+
10+
## Required Flags
11+
12+
These options can only be inferred when running on an existing repository.
13+
Each will be prompted for when creating a new repository if not explicitly provided:
14+
15+
| Flag | Description |
16+
| --------------- | ---------------------------------------------- |
17+
| `--description` | 'Sentence case.' description of the repository |
18+
| `--directory` | which directory and repository name to use |
19+
| `--preset` | starting set of tooling to use |
20+
21+
`npx create-typescript-app` provides three `--preset` options:
22+
23+
1. **Minimal**: Just bare starter tooling: building, formatting, linting, and type checking.
24+
2. **Common**: Bare starters plus testing and automation for all-contributors and releases.
25+
3. **Everything**: The most comprehensive tooling imaginable: sorting, spellchecking, and more!
26+
27+
For example, to create a new repository with the _Everything_ preset and prompt for `description` and `directory`:
28+
29+
```shell
30+
npx create-typescript-app --preset everything
31+
```
32+
33+
Pre-populating all required base options:
34+
35+
```shell
36+
npx create-typescript-app --directory my-app --description "My app! 💖" --preset everything
37+
```
38+
39+
See [Bingo > Stratum > Concepts > Templates > `--preset`](https://www.create.bingo/engines/stratum/concepts/templates#--preset) for more details on presets.
40+
41+
## Optional Flags
42+
43+
The following flags may be provided on the CLI to customize their values.
44+
Each defaults to a value based on the running system, including an repository if transitioning one.
45+
46+
| Flag | Type | Description | Default |
47+
| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
48+
| `--access` | `string` | Which [`npm publish --access`](https://docs.npmjs.com/cli/commands/npm-publish#access) to release npm packages with | `"public"` (TODO: file issue for `readAccess`) |
49+
| `--author` | `string` | Username on npm to publish packages under | An existing npm author, or the currently logged in npm user, or `owner.toLowerCase()` |
50+
| `--bin` | `string` | Value to set in `package.json`'s `"bin"` property, per [FAQs > How can I use `bin`?](./FAQs.md#how-can-i-use-bin) | _(none)_ |
51+
| `--email` | `string` | Email address to be listed as the point of contact in docs and packages (e.g. `[email protected]`) | Yours from `gh`, `git config`, or `npm whoami` |
52+
| `--emoji` | `string` | decorative emoji to use in descriptions and docs | The last emoji from `description`, or `"💖"` |
53+
| `--funding` | `string` | GitHub organization or username to mention in `funding.yml` | The same as `owner` |
54+
| `--keywords` | `string[]` | Any number of keywords to include in `package.json` | _(none)_ |
55+
| `--owner` | `string` | Organization or user owning the repository | Yours from `gh` or `git config` |
56+
| `--pnpm` | `string` | pnpm version for `package.json`'s `packageManager` field | Existing value in `package.json` if it exists |
57+
| `--repository` | `string` | Name for the new repository | The same as `--directory` |
58+
| `--title` | `string` | 'Title Case' title for the repository | Title-cased `repository` |
59+
| `--version` | `string` | package version to publish as and store in `package.json` | Existing value in `package.json` if it exists, or `"0.0.0"` |
60+
61+
For example, customizing the npm author and funding source to different values than what would be inferred:
62+
63+
```shell
64+
npx create-typescript-app --author my-npm-username --funding MyGitHubOrganization
65+
```
66+
67+
Array flags can be specified as space-delineated strings and/or multiple times.
68+
For example, customizing keywords to three:
69+
70+
```shell
71+
npx create-typescript-app --keywords eslint --keywords "javascript typescript"
72+
```
73+
74+
## Block Exclusion Flags
75+
76+
Per [Bingo > Stratum > Concepts > Templates > Exclusion Options](https://www.create.bingo/engines/stratum/concepts/templates#exclusion-options), individual "Blocks" of tooling may be excluded from running.
77+
Each Block may be excluded with a CLI flag whose name matches `--exclude-*`.
78+
79+
For example, initializing with all tooling except for Renovate:
80+
81+
```shell
82+
npx create-typescript-app --exclude-renovate
83+
```
84+
85+
See [Blocks.md](./Blocks.md) for the list of blocks, which presets contain them, and their corresponding `--exclude-*` flags.

‎docs/Configuration Files.md

+177
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Configuration Files
2+
3+
`create-typescript-app` supports a `create-typescript-app.config.js` configuration file per [Bingo > Configuration](https://www.create.bingo/configuration).
4+
Bingo configuration files are generally used for describing complex options that can't be inferred from existing repositories.
5+
`create-typescript-app` is built on the [Stratum engine](https:://create.bingo/engines/stratum/about), so its configuration files adhere to [Bingo > Stratum > Details > Configurations](https://www.create.bingo/engines/stratum/details/configurations):
6+
7+
- [`options`](#options): any type-safe options the template has declared
8+
- [`refinements`](#refinements): any customizations specified by the template
9+
10+
> [!TIP]
11+
> `create-typescript-app` defaults `options` to their values in an existing repository.
12+
> You most likely only need to use `refinements` to specify changes that can't be inferred.
13+
14+
## `options`
15+
16+
Any type-safe options the template has declared.
17+
This includes the options described in [CLI](./CLI.md).
18+
19+
Some of create-typescript-app's options are rich objects, typically very long strings, or otherwise not reasonable on the CLI.
20+
These options are generally only programmatically used internally, but can still be specified in a configuration file:
21+
22+
| Option | Description | Default (If Available) |
23+
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
24+
| `contributors` | AllContributors contributors to store in `.all-contributorsrc` | Existing contributors in the file, or just your username |
25+
| `documentation` | any additional docs to add to `.github/DEVELOPMENT.md` | Extra content in `.github/DEVELOPMENT.md` |
26+
| `existingLabels` | existing labels to switch to the standard template labels | Existing labels on the repository from the GitHub API |
27+
| `explainer` | additional `README.md` sentence(s) describing the package | Extra content in `README.md` after badges and description |
28+
| `guide` | link to a contribution guide to place at the top of development docs | Block quote on top of `.github/DEVELOPMENT.md` |
29+
| `logo` | local image file and alt text to display near the top of the `README.md` | First non-badge image's `alt` and `src` in `README.md` |
30+
| `node` | Node.js engine version(s) to pin and require a minimum of | Values from `.nvmrc` and `package.json`'s `"engines"` |
31+
| `packageData` | additional properties to include in `package.json` | Existing values in `package.json` |
32+
| `rulesetId` | GitHub branch ruleset ID for main branch protections | Existing ruleset on the `main` branch from the GitHub API |
33+
| `usage` | Markdown docs to put in `README.md` under the `## Usage` heading | Existing usage lines in `README.md` |
34+
35+
For example, changing `node` versions to values different from what would be inferred:
36+
37+
```ts
38+
// create-typescript-app.config.js
39+
import { createConfig } from "create-typescript-app";
40+
41+
export default createConfig({
42+
options: {
43+
node: {
44+
minimum: ">=20.19.0",
45+
pinned: "22.14.0",
46+
},
47+
},
48+
});
49+
```
50+
51+
> [!TIP]
52+
> Running `npx create-typescript-app` will apply any new `options` values to the repository.
53+
> You can generally remove `options` from your configuration file after running `npx create-typescript-app`.
54+
55+
## `refinements`
56+
57+
[Refinements](https://www.create.bingo/engines/stratum/details/configurations#refinements) can be used to modify the "Blocks" of tooling provided by create-typescript-app.
58+
59+
See [Blocks.md](./Blocks.md) for the list of blocks, which presets contain them, and their corresponding `--exclude-*` flags.
60+
61+
### `addons`
62+
63+
Any additional [Addons](https://www.create.bingo/engines/stratum/concepts/blocks#addons) provided to Blocks provided by the selected Preset.
64+
65+
For example, this configuration file adds the word `"joshuakgoldberg"` to the CSpell Block's Addons:
66+
67+
```ts
68+
// create-typescript-app.config.js
69+
import { blockCSpell, createConfig } from "create-typescript-app";
70+
71+
export default createConfig({
72+
refinements: {
73+
addons: [
74+
blockCSpell({
75+
words: ["joshuakgoldberg"],
76+
}),
77+
],
78+
},
79+
});
80+
```
81+
82+
Running `npx create-typescript-app` in a repository with that configuration file would add `"joshuakgoldberg"` to the `words` in `cspell.json`.
83+
84+
### `blocks`
85+
86+
Any customizations to the Blocks provided by the selected Preset.
87+
88+
#### `add`
89+
90+
Any Blocks to add to what the Preset provides.
91+
92+
For example, this configuration file adds in `create-typescript-app`'s provided "arethetypeswrong" Block:
93+
94+
```ts
95+
// create-typescript-app.config.js
96+
import { blockAreTheTypesWrong, createConfig } from "create-typescript-app";
97+
98+
export default createConfig({
99+
refinements: {
100+
blocks: {
101+
add: [blockAreTheTypesWrong],
102+
},
103+
},
104+
});
105+
```
106+
107+
Running `npx create-typescript-app` in a repository with that configuration file would add in the created outputs from `blockAreTheTypesWrong`.
108+
109+
#### `exclude`
110+
111+
Any Blocks to exclude from what the Preset provides.
112+
113+
For example, this configuration file omits the default _"This package was templated with..."_ notice that comes with `create-typescript-app`:
114+
115+
```ts
116+
// create-typescript-app.config.js
117+
import { blockTemplatedBy, createConfig } from "create-typescript-app";
118+
119+
export default createConfig({
120+
refinements: {
121+
blocks: {
122+
exclude: [blockTemplatedBy],
123+
},
124+
},
125+
});
126+
```
127+
128+
Running `npx create-typescript-app` in a repository with that configuration file would not include that Block, and so its generated README.md would not include the notice.
129+
130+
#### Custom Blocks and Addons
131+
132+
Custom Blocks can provide Addons to any other Blocks, including those provided by the package.
133+
This allows your repositories to blend in seamlessly with the features provided by your Template.
134+
135+
For example, to add an [`@arethetypeswrong/cli`](https://www.npmjs.com/package/@arethetypeswrong/cli) lint task to the `package.json` file, a repository using the `create-typescript-app` Template could create and use a custom Block:
136+
137+
```ts
138+
// blockLintAreTheTypesWrong.js
139+
import { base, blockPackageJson } from "create-typescript-app";
140+
141+
export const blockLintAreTheTypesWrong = base.createBlock({
142+
about: {
143+
name: "Lint Are The Types Wrong",
144+
},
145+
produce() {
146+
return {
147+
addons: [
148+
blockPackageJson({
149+
properties: {
150+
devDependencies: {
151+
"@arethetypeswrong/cli": "0.17.3",
152+
},
153+
scripts: {
154+
"lint:arethetypeswrong": "attw --pack .",
155+
},
156+
},
157+
}),
158+
],
159+
};
160+
},
161+
});
162+
```
163+
164+
```ts
165+
// create-typescript-app.config.js
166+
import { createConfig } from "create-typescript-app";
167+
168+
import { blockLintAreTheTypesWrong } from "./blockLintAreTheTypesWrong.js";
169+
170+
export default createConfig({
171+
refinements: {
172+
blocks: {
173+
add: [blockLintAreTheTypesWrong],
174+
},
175+
},
176+
});
177+
```

‎docs/FAQs.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ The four presets correspond to what have seemed to be the most common user needs
164164
- Tooling added in this preset should be essential for a TypeScript repository that additionally automates useful GitHub tasks: contributor recognition, release management, and testing.
165165
3. **Everything**: Power users (including this repository) who want as much of the latest and greatest safety checks and standardization as possible.
166166

167-
Note that you can always customize exactly which preset you use per [Options](./Options.md).
167+
Note that you can always customize exactly which preset you use per [CLI](./CLI.md).
168168

169169
## Why does this package include so many tools?
170170

‎docs/Options.md

-73
This file was deleted.

‎docs/Setup.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Hooray! 🥳
2929
## Options
3030

3131
You can customize which pieces of tooling are provided and the options they're created with.
32-
See [Options.md](./Options.md).
32+
See [CLI.md](./CLI.md).
3333

3434
For example, skipping the _"This package was templated with..."_ block:
3535

‎docs/Transition.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,10 @@ Hooray! 🥳
3838
> You'll want to review each of the changes.
3939
> There will almost certainly be some incorrect changes you'll need to fix.
4040
41-
## Options
41+
## CLI Options
4242

4343
You can customize which pieces of tooling are provided and the options they're created with.
44-
See [Options.md](./Options.md).
44+
See [CLI.md](./CLI.md).
4545

4646
For example, skipping the _"This package was templated with..."_ block:
4747

0 commit comments

Comments
 (0)