Skip to content

Commit b059ca7

Browse files
authored
docs: add TypeScript explainer to docs site
Typescript docs
2 parents b797aaf + dad313a commit b059ca7

File tree

1 file changed

+45
-9
lines changed

1 file changed

+45
-9
lines changed

README.md

+45-9
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,47 @@ $ plop component -- --type react
130130
### Running a Generator Forcefully
131131
By default Plop actions keep your files safe by failing when things look fishy. The most obvious example of this is not allowing an [`add`](#add) action to overwrite a file that already exists. Plop actions individually support the `force` property but you can also use the `--force` flag when running Plop from the terminal. Using the `--force` flag will tell every action to run forcefully. With great power...🕷
132132

133+
### Using TypeScript plopfiles
134+
135+
Plop bundles TypeScript declarations and supports TypeScript plopfiles via [tsx loaders](https://github.com/privatenumber/tsx?tab=readme-ov-file#nodejs-loader), a feature of [NodeJS command line imports](https://nodejs.org/api/cli.html#--importmodule).
136+
137+
First, make a TypesScript plopfile:
138+
139+
```ts
140+
// plopfile.ts
141+
import {NodePlopAPI} from 'plop';
142+
143+
export default function (plop: NodePlopAPI) {
144+
// plop generator code
145+
};
146+
```
147+
148+
Next, install [tsx](https://github.com/privatenumber/tsx) and optionally [cross-env](https://www.npmjs.com/package/cross-env):
149+
150+
```bash
151+
npm i -D tsx cross-env
152+
```
153+
154+
Finally, use `NODE_OPTIONS` to activate the tsx loader. Now Plop can import your `plopfile.ts`:
155+
156+
**Node.js v20.6 and above**
157+
158+
```json
159+
// package.json
160+
"scripts": {
161+
"cross-env NODE_OPTIONS='--import tsx' plop --plopfile=plopfile.ts"
162+
}
163+
```
164+
165+
**Node.js v20.5.1 and below**
166+
167+
```json
168+
// package.json
169+
"scripts": {
170+
"cross-env NODE_OPTIONS='--loader tsx' plop --plopfile=plopfile.ts"
171+
}
172+
```
173+
133174
## Why Generators?
134175
Because when you create your boilerplate separate from your code, you naturally put more time and thought into it.
135176

@@ -140,18 +181,13 @@ Because [context switching is expensive](https://www.petrikainulainen.net/softwa
140181
# Plopfile API
141182
The plopfile api is the collection of methods that are exposed by the `plop` object. Most of the work is done by [`setGenerator`](#setgenerator) but this section documents the other methods that you may also find useful in your plopfile.
142183

143-
## TypeScript Declarations
184+
## TypeScript Support
144185

145-
`plop` bundles TypeScript declarations. Whether or not you write your plopfile in TypeScript, many editors will offer code assistance via these declarations.
186+
Plop bundles TypeScript declarations. See [using TypeScript plopfiles](#using-typescript-plopfiles) for more details.
146187

147-
```javascript
148-
// plopfile.ts
149-
import {NodePlopAPI} from 'plop';
188+
## JSDoc Support
150189

151-
export default function (plop: NodePlopAPI) {
152-
// plop generator code
153-
};
154-
```
190+
Whether or not you write your plopfile in TypeScript, many editors will offer code assistance via JSDoc declarations.
155191

156192
```javascript
157193
// plopfile.js

0 commit comments

Comments
 (0)