diff --git a/.changeset/fresh-coins-teach.md b/.changeset/fresh-coins-teach.md new file mode 100644 index 0000000..c501941 --- /dev/null +++ b/.changeset/fresh-coins-teach.md @@ -0,0 +1,5 @@ +--- +'@emigrate/cli': minor +--- + +Add support for loading TypeScript migration files in the default loader diff --git a/.changeset/tough-snakes-float.md b/.changeset/tough-snakes-float.md new file mode 100644 index 0000000..a84cd4e --- /dev/null +++ b/.changeset/tough-snakes-float.md @@ -0,0 +1,5 @@ +--- +'@emigrate/cli': minor +--- + +Add a guide for running migration files written in TypeScript to the documentation diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 6d0a145..063a49e 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -98,6 +98,15 @@ export default defineConfig({ }, ], }, + { + label: 'Guides', + items: [ + { + label: 'Using TypeScript', + link: '/guides/typescript/', + }, + ], + }, { label: 'Plugins', items: [ diff --git a/docs/src/content/docs/commands/up.mdx b/docs/src/content/docs/commands/up.mdx index 64db94c..2c2dd8a 100644 --- a/docs/src/content/docs/commands/up.mdx +++ b/docs/src/content/docs/commands/up.mdx @@ -72,7 +72,8 @@ The directory where the migration files are located. The given path should be ab A module to import before running the migrations. This option can be specified multiple times. -Can for instance be used to load environment variables using [dotenv](https://github.com/motdotla/dotenv) with `--import dotenv/config`. +Can for instance be used to load environment variables using [dotenv](https://github.com/motdotla/dotenv) with `--import dotenv/config`, +or for running migrations in NodeJS written in TypeScript with [tsx](https://github.com/privatenumber/tsx) (`--import tsx`), see the TypeScript guide for more information. ### `-s`, `--storage ` diff --git a/docs/src/content/docs/guides/example.md b/docs/src/content/docs/guides/example.md deleted file mode 100644 index ebd0f3b..0000000 --- a/docs/src/content/docs/guides/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Guide -description: A guide in my new Starlight docs site. ---- - -Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. -Writing a good guide requires thinking about what your users are trying to do. - -## Further reading - -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/docs/src/content/docs/guides/typescript.mdx b/docs/src/content/docs/guides/typescript.mdx new file mode 100644 index 0000000..8e580a4 --- /dev/null +++ b/docs/src/content/docs/guides/typescript.mdx @@ -0,0 +1,132 @@ +--- +title: Using TypeScript +description: A guide on how to support migration files written in TypeScript +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import Link from '@components/Link.astro'; + +:::tip[Using Bun or Deno?] +If you are using [Bun](https://bun.sh) or [Deno](https://deno.land) you are already good to go as they both support TypeScript out of the box. +::: + +You have at least the two following options to support running TypeScript migration files in NodeJS. + +## Using `tsx` + +If you want to be able to write and run migration files written in TypeScript the easiest way is to install the [`tsx`](https://github.com/privatenumber/tsx) package. + +### Installing `tsx` + + + + ```bash + npm install tsx + ``` + + + ```bash + pnpm add tsx + ``` + + + ```bash + yarn add tsx + ``` + + + +:::note +You must install `tsx` as an ordinary dependency, not as a dev dependency, +in case you are pruning your development dependencies before deploying your application (which you should). +::: + +### Loading TypeScript migrations + +After installing `tsx` you can load it in two ways. + +#### Via CLI + +Using the `--import` flag you can load `tsx` before running your migration files. + + + + ```bash + npx emigrate up --import tsx + ``` + + + ```bash + pnpm emigrate up --import tsx + ``` + + + ```bash + yarn emigrate up --import tsx + ``` + + + +#### Via configuration file + +You can also directly import `tsx` in your configuration file. + +```js title="emigrate.config.js" {1} +import 'tsx'; + +export default { + // ... +}; +``` + +Then you can run your migration files as usual: + + + + ```bash + npx emigrate up + ``` + + + ```bash + pnpm emigrate up + ``` + + + ```bash + yarn emigrate up + ``` + + + +## Building TypeScript migrations + +If you don't want to have `tsx` (or similar) as a dependency included in your production environment then +you can build your TypeScript migration files using the [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) compiler or +some other tool that are already part of your build process when transpiling your TypeScript code to JavaScript. + +Assume that you have all of your migrations in a `src/migrations` directory and you have built them to a `dist/migrations` directory. + +Then you can run your migration files by pointing to the `dist/migrations` directory: + + + + ```bash + npx emigrate up -d dist/migrations + ``` + + + ```bash + pnpm emigrate up -d dist/migrations + ``` + + + ```bash + yarn emigrate up -d dist/migrations + ``` + + + +:::note +If you're mixing languages for your migration files, e.g. you have both `.sql` and `.ts` files in `src/migrations`, make sure that they are all copied to the destination directory if not part of the TypeScript build process. +::: diff --git a/docs/src/content/docs/plugins/loaders/default.mdx b/docs/src/content/docs/plugins/loaders/default.mdx index d7c32b3..2c881bc 100644 --- a/docs/src/content/docs/plugins/loaders/default.mdx +++ b/docs/src/content/docs/plugins/loaders/default.mdx @@ -3,8 +3,9 @@ title: Default Loader Plugin --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +import Link from '@components/Link.astro'; -The default loader plugin is responsible for importing migration files written in JavaScript. +The default loader plugin is responsible for importing migration files written in JavaScript or TypeScript. Migration files can be written using either CommonJS or ES Modules. ## Supported extensions @@ -14,6 +15,13 @@ The default loader plugin supports the following extensions: * `.js` - either CommonJS or ES Modules depending on your package.json's [`type` field](https://nodejs.org/api/packages.html#type) * `.cjs` - CommonJS * `.mjs` - ES Modules +* `.ts` - either CommonJS or ES Modules written in TypeScript +* `.cts` - CommonJS written in TypeScript +* `.mts` - ES Modules written in TypeScript + +:::note +To enable TypeScript support in NodeJS you also need to follow the TypeScript setup guide. +::: ## Supported exports diff --git a/packages/cli/src/plugin-loader-js.ts b/packages/cli/src/plugin-loader-js.ts index 3a502ac..1f044fe 100644 --- a/packages/cli/src/plugin-loader-js.ts +++ b/packages/cli/src/plugin-loader-js.ts @@ -17,7 +17,7 @@ const promisifyIfNeeded = (fn: T) => { }; const loaderJs: LoaderPlugin = { - loadableExtensions: ['.js', '.cjs', '.mjs'], + loadableExtensions: ['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts'], async loadMigration(migration) { const migrationModule: unknown = await import(migration.filePath);