[TS] [PLOP 3] Improve documentation for TS usage

[beaussan]

From the docs, you need ts-node installed, typescript and it should just works ✨

However, it doesn't work for me, I created a reproduction repo, it's like the typescript example, without the .js file

Expected output

It works !

Result

It won't work at all

$ npm run plop
[PLOP] Something went wrong with reading your plop file TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /REDACTED/plop-reproduction/plopfile.ts
    at new NodeError (internal/errors.js:322:7)
    at Loader.defaultGetFormat [as _getFormat] (internal/modules/esm/get_format.js:71:15)
    at Loader.getFormat (internal/modules/esm/loader.js:105:42)
    at Loader.getModuleJob (internal/modules/esm/loader.js:243:31)
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async Loader.import (internal/modules/esm/loader.js:177:17)
    at async nodePlop (file:///REDACTED/plop-reproduction/node_modules/node-plop/src/node-plop.js:198:26)
    at async Liftoff.run (file:///REDACTED/plop-reproduction/node_modules/plop/src/plop.js:56:12) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

Reproduction : https://github.com/beaussan/plop-reproduction

[crutchcorn]

Are you running tsc to compile your .ts file to .js beforehand? It's unclear from the repro

[beaussan]

No I don't, and from the pr updating the typescript example (linked in the changelog), I thought it wasn't a needed step

[crutchcorn]

Ahh, gotcha. FWIW that PR is incomplete, but we do need better docs. I'm gonna go ahead and make a GH issue for future v4 baked-in no-compiling-needed support, but if possible, let's go ahead and change this issue to read something like:

"Improve TS usage documentation" and highlight adding a mention of a compilation step

[crutchcorn]

Added issue for supporting without compile step:

#297

[beaussan]

Got it ! I got this impression from this : #192 (comment) and I must say I spend some days trying to setup typescript without too much issue (path need to be adapted to be from the tsc output and not the ts source for example).

I'll modify the issue to reflect this instead then ! :) Thanks for the quick response, and for plop, it's a amazing software

[gustaff-weldon]

I have a similar problem when doing the upgrade to 3.0. With 2.x I was using a shebang script with ts-node to kick-off plop.
My plopfile.ts worked like a charm. I did not even need tsconfig.json.

With 3.0 it's a whole slew of problems.

1. Shebang does not work anymore, for a file:

#!/usr/bin/env ts-node

import minimist from "minimist";
import { Plop, run } from "plop";
import process from "process";

const args = process.argv.slice(2);
const argv = minimist(args);

Plop.prepare({
  cwd: argv.cwd,
  configPath: argv.plopfile,
  preload: argv.preload || [],
  completion: argv.completion
}, env => Plop.execute(env,  (env) => {
  return run(env, undefined, true)
}));

it throws

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension "" for /Users/me/projectroot/bin/plop
    at new NodeError (node:internal/errors:371:5)
    at Object.file: (node:internal/modules/esm/get_format:72:15)
    at defaultGetFormat (node:internal/modules/esm/get_format:85:38)
    at defaultLoad (node:internal/modules/esm/load:13:42)
    at ESMLoader.load (node:internal/modules/esm/loader:303:26)
    at ESMLoader.moduleProvider (node:internal/modules/esm/loader:230:58)
    at new ModuleJob (node:internal/modules/esm/module_job:63:26)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:244:11)
    at async Promise.all (index 0)
    at async ESMLoader.import (node:internal/modules/esm/loader:281:24) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

After some digging I have solved the 1) by:

• adding "type": "module" to my package.json,
• moving my shebang script to to plop.ts
• adding the following tsconfig.json

  {
    "compilerOptions": {
      "importsNotUsedAsValues": "error",
      "isolatedModules": true,
      "esModuleInterop": true,
      "forceConsistentCasingInFileNames": true,
      "module": "ES2020",
      "moduleResolution": "node",
      "target": "ES2015",
      "strict": true,
    },
    "include": [
      "**/*.ts"
    ],
    "exclude": ["node_modules"]
  }
  

• And starting plop with --loader ts-node/esm:

  node --loader ts-node/esm ./plop.ts
  

2. This is where I started getting a problem with imports in my plopfile.ts...

[PLOP] Something went wrong with reading your plop file CustomError: Cannot find module [PLOP] Something went wrong with reading your plop file CustomError: Cannot find module '/Users/me/projectroot/config/deployment' imported from /Users/me/projectroot/plopfile.ts
    at finalizeResolution (/Users/me/projectroot/node_modules/ts-node/dist-raw/node-esm-resolve-implementation.js:383:11)
    at moduleResolve (/Users/me/projectroot/node_modules/ts-node/dist-raw/node-esm-resolve-implementation.js:818:10)
    at Object.defaultResolve (/Users/me/projectroot/node_modules/ts-node/dist-raw/node-esm-resolve-implementation.js:929:11)
    at /Users/me/projectroot/node_modules/ts-node/src/esm.ts:152:38
    at Generator.next (<anonymous>)
    at /Users/me/projectroot/node_modules/ts-node/dist/esm.js:8:71
    at new Promise (<anonymous>)
    at __awaiter (/Users/me/projectroot/node_modules/ts-node/dist/esm.js:4:12)
    at resolve (/Users/me/projectroot/node_modules/ts-node/dist/esm.js:48:16)
    at ESMLoader.resolve (node:internal/modules/esm/loader:422:30)

which lead me to TypeStrong/ts-node#1007 and https://dev.to/asteinarson/typescript-nodejs-and-es6-esm-modules-18ea

I have solved 2) with:

• adding --experimental-specifier-resolution=node
• running the plop with:

node --experimental-specifier-resolution=node --loader ts-node/esm ./plop.ts

I'm able to run Plop 3.0 now, but I'm getting experimental flag warnings:

(node:900) ExperimentalWarning: --experimental-loader is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

Apart from taking a good chunk of my day to figure out what is going on, the result is less than ideal. Any input on how to make it better, will be appreciated

[crutchcorn]

Unfortunately, due to the state of ESM in TS today (and, by extension, ts-node), there's not a ton we can do in terms of making that process too much better @gustaff-weldon without some dev lift on our end.

We're tracking some thoughts on #297 to make this possible and a lot better (namely #297 (comment)), but that might be a couple of months out. I wish the situation was better, but this is an unfortunate inherent result of supporting ESM (which was a requirement to patch out some "moderate" vulns in deps)

[gustaff-weldon]

@crutchcorn understood.
I was wondering perhaps if I'm missing some knowledge that would make this puzzle simpler.
For now, I given up and added --no-warnings flag to suppress that loader message for our users.

Fingers crossed for the #297 getting implemented, it looks promising :)

[crutchcorn]

This issue is really two things:

1. Previously, we did not have an example of compiling a plopfile.js from TypeScript to MJS/CJS. This has now been done and even has tests backing up that it does indeed work with basic tsc && plop usage
2. We want to support TypeScript OOTB without any additional configuration

Since # 1 is the main topic of discussion in this particular issue, I will be closing it in favor of #297 for # 2

[ryparker]

What's the recommended setup for typescript support? Is it not supported right now? Hard to find an answer across the GitHub issues. The typescript guidance from the docs lead me to the error reported in this issue.

[fandyPham]

i already downgrade version from 3. to 2. :D

[viveleroi]

I am not following what's supposed to be done here. I have typescript already running fine in our app, I added the plopfile.ts based on the docs and just get the error [PLOP] Something went wrong with reading your plop file TypeError: Unknown file extension ".ts".

I looked at the example above and it's just got typescript with a standard tsconfig (we have the same required settings) and nothing else? Not sure what I'm missing here

[pfcodes]

I am not following what's supposed to be done here. I have typescript already running fine in our app, I added the plopfile.ts based on the docs and just get the error [PLOP] Something went wrong with reading your plop file TypeError: Unknown file extension ".ts".

I looked at the example above and it's just got typescript with a standard tsconfig (we have the same required settings) and nothing else? Not sure what I'm missing here

Same. I ended up just doing

// plopfile.js
export default function (
  /** @type {import('plop').NodePlopAPI} */
  plop,
) {}