{"id":26552106,"url":"https://github.com/septh/ts-run","last_synced_at":"2025-03-22T08:23:49.992Z","repository":{"id":216592463,"uuid":"741730037","full_name":"Septh/ts-run","owner":"Septh","description":"The minimalist TypeScript script runner for NodeJS","archived":false,"fork":false,"pushed_at":"2024-11-29T21:54:25.000Z","size":449,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-01T14:03:34.420Z","etag":null,"topics":["node","runner","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Septh.png","metadata":{"files":{"readme":".github/README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":"Septh","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://paypal.me/septh07"]}},"created_at":"2024-01-11T01:47:27.000Z","updated_at":"2025-01-04T13:38:47.000Z","dependencies_parsed_at":"2024-05-28T06:18:06.638Z","dependency_job_id":"3cd374f0-ad39-4fe2-90c7-95b9b935d04d","html_url":"https://github.com/Septh/ts-run","commit_stats":null,"previous_names":["septh/ts-run"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Fts-run","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Fts-run/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Fts-run/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Septh%2Fts-run/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Septh","download_url":"https://codeload.github.com/Septh/ts-run/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244927026,"owners_count":20533231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node","runner","typescript"],"created_at":"2025-03-22T08:23:49.392Z","updated_at":"2025-03-22T08:23:49.986Z","avatar_url":"https://github.com/Septh.png","language":"TypeScript","funding_links":["https://patreon.com/Septh","https://paypal.me/septh07"],"categories":[],"sub_categories":[],"readme":"# ts-run\n\u003e The minimalist TypeScript script runner for NodeJS.\n\n### Features\n- Just-in-time TypeScript transpilation so fast you won't even notice.\n- Generates source maps for accurate stack traces.\n- Does not spawn another process to transpile TypeScript.\n- Does not spawn another Node process to run your script.\n- Strictly follows modern Node semantics for ESM and CommonJS modules.\n- Zero config: no config file, no command line arguments, no environment variables, no nothing.\n- Does not even need a `tsconfig.json`.\n- Extra-light: only 220 kilobytes installed!\n- Zero dependency!\n\n### Non-features\n- Not for running full-blown TypeScript projects.\n- No REPL support.\n\n\n## About\n`ts-run` is a CLI command that you can use to run TypeScript scripts in NodeJS as if they were written in plain JavaScript. It is a simple as:\n\n```sh\nts-run ./some-script.ts\n```\n\nThe idea is that you take advantage of your IntelliSense-compatible editor to author your scripts with full type checking on, and `ts-run` will transparently run them without you having to run the TypeScript compliler beforehand.\n\n\n## Installation and usage\n`ts-run` requires a modern (as of january 2024) version of NodeJS:\n- Node 18 version 18.19.0 or later\n- Node 20 version 20.6.0 or later\n- Any version \u003e= 21\n\n#### Global install\nFor everyday use, you may want to install `ts-run` globally:\n\n```sh\nnpm install -g @septh/ts-run\n```\n\nso it's always available in your CLI:\n\n```sh\nts-run path/to/some/script.ts\n```\n\n\n#### Local install\nOr you may install it locally in a project:\n\n```sh\n# with npm\nnpm install --save-dev @septh/ts-run\n\n# with pnpm\npnpm add --save-dev @septh/ts-run\n\n# with yarn\nyarn add --dev @septh/ts-run\n```\n\nand then call it from the `scripts` section in `package.json`:\n\n```json\n{\n    \"scripts\": {\n        \"get-data\": \"ts-run ./scripts/download-data.ts\",\n        \"release\": \"ts-run ./scripts/prepare-release.ts\"\n    }\n}\n```\n\nor from the command line:\n\n```sh\n# with npx\nnpx ts-run ./scripts/do-something.ts\n\n# with node --import\nnode --import=@septh/ts-run ./scripts/do-something.ts\n```\n\n\n## TypeScript to JavaScript considerations\n`ts-run`'s sole role is to transpile TypeScript code to JavaScript code, no more, no less. It does not try to optimize or minify your code and it does not downlevel nor polyfill JavaScript. Therefore, there are a few things you should keep in mind while authoring your scripts.\n\n### imports and exports\n\n`ts-run` handles `import` and `export` declarations as one would expect. In short:\n\n* The `import ... from 'specifier'` syntax is left as is in ES modules and transformed to `const ... = require('specifier')` in CommonJS modules.\n* The `import namespace = require('specifier')` syntax is valid in ES modules only and is transformed to `const require = createRequire(import.meta.url); const namespace = require('specifier')`, with the [createRequire()](https://nodejs.org/api/module.html#modulecreaterequirefilename) call being hoisted if used several times.\n* Dynamics imports are always left untouched, even in CJS modules.\n* `export`s are transformed to `module.exports` assignments in CommonJS modules.\n* Type-only `import`s and `export`s, whether explicit (with the `type` keyword) or implicit, are silently removed.\n\n#### Specifiers\nGiven the above, you should simply import your `.ts` scripts as you would with plain Javascript:\n\n```ts\n// a.ts\nexport const something = 'great'\n```\n\n```ts\n// b.ts\nimport { something } from './a.ts'\n```\n\nBeginning with 1.2.6, `.js` specifiers are also supported:\n\n```ts\n// b.ts\nimport { something } from './a.js'  // works too\n```\n\nHowever, using .`ts` specifiers is highly recommended as a mean to ensure a smooth transition with [Node's own `--experimental-strip-types` option](https://nodejs.org/api/typescript.html#type-stripping).\n\n#### TypeScript specificities\nTypeScript's module resolution specificities are not handled; instead, Node's module resolution algorithm is always used. In other words, `ts-run` always acts as if both `moduleResolution` and `module` were set to `Node16` and `paths` was empty.\n\n### Sucrase\n`ts-run` uses a customized build of [Sucrase](https://github.com/alangpierce/sucrase) under the hood and therefore exhibits the same potential bugs and misbehaviors as Sucrase.\n\nOf particular attention, the following quote from Sucrase's README:\n\u003e Decorators, private fields, throw expressions, generator arrow functions, and do expressions are all unsupported in browsers and Node (as of this writing), and Sucrase doesn't make an attempt to transpile them.\n\nApart from this, if `ts-run` doesn't seem to work as you'd expect, you should first check if there is a [Sucrase issue](https://github.com/alangpierce/sucrase/issues) open for your problem.\n\n\n## Authoring your scripts\nAs stated earlier, `ts-run` does not need (and in fact, does not even look for) a `tsconfig.json` file.\n\nThe same is not true however for the TypeScript Language Server that your IntelliSense-aware editor relies on. You'll find the following `tsconfig.json` useful to get the right warnings and errors reports in your IDE:\n\n```jsonc\n{\n  \"compilerOptions\": {\n\n    // This tells the TypeScript language server that this directory contains Node scripts.\n    // \"Bundler\" would be fine, too.\n    \"module\": \"Node16\",\n\n    // For scripts that use .ts import specifiers (recommended)\n    // Please note that `noEmit` is required when using `allowImportingTsExtensions`\n    \"allowImportingTsExtensions\": true,\n    \"noEmit\": true,\n\n    // Scripts are transpiled in isolation; this imposes a few restrictions\n    // on some TypeScript features like const enums or namespaces.\n    // (see https://www.typescriptlang.org/tsconfig#isolatedModules)\n    \"isolatedModules\": true,\n\n    // Of course, add any other type-checking options you deem necessary:\n    \"strict\": true\n    // etc.\n  }\n}\n```\n\nFor reference, you can find such a `tsconfig.json` file in the [test](./test/tsconfig.json) directory of this repository.\n\n\n## Using with a test-runner\nI have tested `ts-run` with [ava](https://github.com/avajs/ava) and [Node itself](https://nodejs.org/api/test.html) and it works very well in both cases. I can see no reason why it wouldn't work with another test-runner.\n\n### With node:test\nThis very repo is using Node as its test-runner of choice. Here's what your `scripts` section in `package.json` might look like:\n\n```json\n  \"scripts\": {\n    \"test\": \"node --import=@septh/ts-run --test test/**/*.test.{ts,mts,cts}\"\n  }\n```\n\n\u003e Note: to pass command line options to Node itself, you need to use the `--import` syntax as shown above.\n\n### With ava\nAdd the following entry to your `package.json`:\n\n```jsonc\n  \"ava\": {\n    \"extensions\": {\n      \"ts\": \"module\",     // Or \"commonjs\", depending on what your package.json says\n      \"mts\": \"module\",\n      \"cts\": \"commonjs\"\n    },\n    \"nodeArguments\": [\n      \"--import=@septh/ts-run\"\n    ]\n  }\n```\n\nHere's a real-life example: https://github.com/Septh/rollup-plugin-node-externals\n\n### With other test-runners\nAny test-runner that provides a mean to specify Node arguments (just like ava above) should work happily with `ts-run`.\n\nIn the worst case, you can always use the `NODE_OPTIONS` environment variable:\n```sh\nNODE_OPTIONS=\"--import=@septh/ts-run\" my-test-runner\n```\n\n\n## Debugging scripts with VS Code\nBecause `ts-run` generates sourcemaps, you can set breakpoints in your script, inspect variables, etc.\n\nEither run `ts-run` in the VS Code Javascript Debug Terminal or use the following `launch.json` configuration (replace `\u003cpath/to/your/script.ts\u003e` with the actual path to your script):\n\n```jsonc\n{\n    // Use IntelliSense to learn about possible attributes.\n    // Hover to view descriptions of existing attributes.\n    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Run with ts-run\",\n            \"request\": \"launch\",\n            \"type\": \"node\",\n            \"runtimeArgs\": [\n                \"--import=@septh/ts-run\"\n            ],\n            \"program\": \"${workspaceFolder}/\u003cpath/to/your/script.ts\u003e\",\n            \"skipFiles\": [\n                \"\u003cnode_internals\u003e/**\",\n                \"**/node_modules/**\"\n            ]\n        }\n    ]\n}\n```\n\n\n## Licence\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsepth%2Fts-run","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsepth%2Fts-run","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsepth%2Fts-run/lists"}