airbnb / ts-migrate

A tool to help migrate JavaScript code quickly and conveniently to TypeScript
MIT License
5.42k stars 218 forks source link

Add documentation regarding the use of plugins #166

Open egilll opened 2 years ago

egilll commented 2 years ago

There doesn't appear to be any documentation regarding the use of plugins. It turns out there is a --plugin flag which can activate specific plugins. However, I cannot figure out how options are sent to plugins via the command line, which is why I'm opening an issue instead of submitting a pull request.

I want to suggest adding something along the lines of the following to packages/ts-migrate:


# Plugins

Plugins can be found in [ts-migrate-plugins](./../ts-migrate-plugins/). To run only a specific plugin, use the `--plugin` option. For example, to use the JSDoc plugin, run:

> npx ts-migrate-full . --plugin jsdoc

Consult the source code of the plugins in question regarding further available options. To run the JSDoc plugin with the `annotateReturns` option on, run: 

> npx ts-migrate-full . --plugin jsdoc --annotateReturns (???)
michaeljaltamirano commented 2 years ago

There is some information about the plugins via the CLI, though I agree that some Github documentation may be helpful. My steps for discovering this were:

  1. Reading the general CLI --help output:
yarn ts-migrate --help
Usage: npm run ts-migrate -- <command> [options]

Commands:
  npm run ts-migrate -- init <folder>               Initialize tsconfig.json file in <folder>
  npm run ts-migrate -- init:extended <folder>      Initialize tsconfig.json file in <folder>
  npm run ts-migrate -- rename [options] <folder>   Rename files in folder from JS/JSX to TS/TSX
  npm run ts-migrate -- migrate [options] <folder>  Fix TypeScript errors, using codemods
  npm run ts-migrate -- reignore <folder>           Re-run ts-ignore on a project

Options:
  -h, --help  Show help                                                                    [boolean]

Examples:
  npm run ts-migrate -- --help                        Show help
  npm run ts-migrate -- migrate --help                Show help for the migrate command
  npm run ts-migrate -- init frontend/foo             Create tsconfig.json file at
                                                      frontend/foo/tsconfig.json
  npm run ts-migrate -- init:extended frontend/foo    Create extended from the base tsconfig.json
                                                      file at frontend/foo/tsconfig.json
  npm run ts-migrate -- rename frontend/foo           Rename files in frontend/foo from JS/JSX to
                                                      TS/TSX
  npm run ts-migrate -- rename frontend/foo --s       Rename files in frontend/foo/bar/baz from
  "bar/baz"                                           JS/JSX to TS/TSX
  1. Running the migrate-specific --help command:
yarn ts-migrate migrate --help
npm run ts-migrate -- migrate [options] <folder>

Fix TypeScript errors, using codemods

Positionals:
  folder                                                                         [string] [required]

Options:
  -h, --help     Show help                                                                 [boolean]
  --plugin       Run a specific plugin
             [string] [choices: "add-conversions", "declare-missing-class-properties", "eslint-fix",
                             "explicit-any", "hoist-class-statics", "jsdoc", "member-accessibility",
         "react-class-lifecycle-methods", "react-class-state", "react-default-props", "react-props",
                                                      "react-shape", "strip-ts-ignore", "ts-ignore"]
  --sources, -s  Path to a subset of your project to rename (globs are ok).                 [string]

Examples:
  migrate /frontend/foo                               Migrate all the files in /frontend/foo
  npm run ts-migrate -- migrate /frontend/foo -s      Migrate all the files in /frontend/foo/bar,
  "bar/**/*" -s "node_modules/**/*.d.ts"              accounting for ambient types from
                                                      node_modules.
  npm run ts-migrate -- migrate /frontend/foo         Migrate JSDoc comments for all the files in
  --plugin jsdoc                                      /frontend/foo

Related: https://github.com/airbnb/ts-migrate/pull/147