docs: website (#527)

.gitignore

@@ -27,3 +27,6 @@ dist
 
 # Link config
 link.config.json
+
+# Vitepress
+docs/.vitepress/cache

docs/.vitepress/config.ts

@@ -0,0 +1,66 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+	lang: 'en-US',
+
+	title: 'tsx',
+
+	description: 'tsx (TypeScript Execute) - The easiest way to run TypeScript in Node.js',
+
+	lastUpdated: true,
+
+	cleanUrls: true,
+
+	ignoreDeadLinks: true,
+
+	metaChunk: true,
+
+	themeConfig: {
+		siteTitle: 'tsx',
+
+		editLink: {
+			pattern: 'https://github.com/privatenumber/tsx/edit/develop/docs/:path',
+			text: 'Edit this page on GitHub',
+		},
+
+		nav: [
+			{ text: 'Discussions', link: 'https://github.com/privatenumber/tsx/discussions' },
+		],
+
+		sidebar: [
+			{
+				text: 'Introduction',
+				items: [
+					{ text: 'What is tsx?', link: '/' },
+					{ text: 'Getting Started', link: '/getting-started' },
+				],
+			},
+			{
+				text: 'Usage',
+				items: [
+					{ text: 'Basic usage', link: '/usage' },
+					{ text: 'Watch mode', link: '/watch-mode' },
+					{ text: 'Scripts', link: '/scripts' },
+				]
+			},
+			{
+				text: 'Integration',
+				items: [
+					{ text: 'Node.js', link: '/node' },
+					{ text: 'VSCode', link: '/vscode' },
+				]
+			},
+			{
+				text: 'FAQ',
+				link: '/faq',
+			},
+		],
+
+		socialLinks: [
+			{
+				icon: 'github',
+				link: 'https://github.com/privatenumber/tsx',
+			},
+		],
+	},
+});

docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme';
+import './styles.css';
+
+export default DefaultTheme;

docs/.vitepress/theme/styles.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

docs/faq.md

@@ -0,0 +1,92 @@
+# Frequently Asked Questions
+
+## How can I do __ in _tsx_?
+
+It's important to remember that `tsx` is a Node.js enhancement—it's still Node underneath.
+
+That said, often times you might want to ask and lookup the following instead:
+- _"How can I do __ in Node.js?"_
+- _"How can I do __ in TypeScript?"_
+
+
+## Who uses _tsx_?
+
+_tsx_ currently gets <a href="https://npm.im/tsx"><img class="inline-block" src="https://badgen.net/npm/dm/tsx"></a> and is used by many projects.
+
+Here are some notable ones I've found via [GitHub Search](https://github.com/search?q=path%3Apackage.json+%22%5C%22tsx%5C%22%3A+%5C%22%22&type=code):
+
+### Projects
+- [Vite](https://github.com/vitejs/vite/blob/6cccef78a52492c24d9b28f3a1784824f34f5cc3/package.json#L83)
+- [Vue.js](https://github.com/vuejs/core/blob/70641fc0deb857464d24aa7ab7eaa18e2a855146/package.json#L110)
+- [Mermaid](https://github.com/mermaid-js/mermaid/blob/3809732e48a0822fad596d0815a6dc0e166dda94/package.json#L121)
+- [date-fns](https://github.com/date-fns/date-fns/blob/5c1adb5369805ff552737bf8017dbe07f559b0c6/package.json#L6123)
+- [Cheerio](https://github.com/cheeriojs/cheerio/blob/d0b3c2f6b57cd1f835741175d463963266be0eef/package.json#L99)
+
+### Companies
+- Vercel: [Turbo](https://github.com/vercel/turbo/blob/adbfe4c04e3cdd31ae1916d0a5222bbc5ae2bb58/packages/turbo-repository/package.json#L20), [Serve](https://github.com/vercel/serve/blob/1ea55b1b5004f468159b54775e4fb3090fedbb2b/package.json#L61), [AI](https://github.com/vercel/ai/blob/e94fb321645bfff7ecc78bb195ccd34af1a40c74/examples/ai-core/package.json#L20)
+- Google: [Angular](https://github.com/angular/angular/blob/a34267b72e8994d22d47c73d45f22173304939a0/package.json#L144), [\[1\]](https://github.com/google/neuroglancer/blob/d5cc03520b24ef1c66d7fb6b3a3b49eebe87bd44/package.json#L69), [\[2\]](https://github.com/google/labs-prototypes/blob/93a0fba516d95e4fc7063b9c38d1074f69322d2d/seeds/team-experiments/package.json#L25)
+- GitHub: [\[1\]](https://github.com/github/docs/blob/d183c8519bb08678150e7c4b45c50fb314a2d145/package.json#L273), [\[2\]](https://github.com/github/local-action/blob/a93157e99d69c563c0368bb8fd2a3c6f5c6795ea/package.json#L53)
+- Square (internal projects)
+- Supabase: [Supabase](https://github.com/supabase/supabase/blob/34d152ce7832a1313f06012612480b9717742f73/apps/docs/package.json#L101), [\[1\]](https://github.com/supabase/stripe-sync-engine/blob/01ab4093d31fad974d85d78c52b4130779dc0eeb/package.json#L55), [\[2\]](https://github.com/supabase/storage/blob/2adeac7ddb41522df3ee30b8d4cf9071426bbe5f/package.json#L103), [\[3\]](https://github.com/supabase/orb-sync-engine/blob/e3249cca02c3a7f3b385fdd9ea1f72d5eb55fb05/apps/node-fastify/package.json#L27)
+- Astro: [Compiler](https://github.com/withastro/compiler/blob/17f89322a5604542735b13fdedd2664253f1e8f8/package.json#L35), [Starlight](https://github.com/withastro/starlight/blob/b2c50ea1da1aaefd1f0f08dd2f501c8dc4f04726/packages/file-icons-generator/package.json#L12), [\[1\]](https://github.com/withastro/language-tools/blob/0503392b80765c8a1292ddc9c063a1187425c187/packages/astro-check/package.json#L38)
+
+
+
+## How does _tsx_ compare to [`ts-node`](https://github.com/TypeStrong/ts-node)?
+
+`tsx` and `ts-node` are both designed for executing TypeScript in Node.js, but offer different approaches to suit user preferences.
+
+- **Simple installation**
+
+	_tsx_ is offered as a single binary without peer dependencies, and can be used without installation (just run `npx tsx ./script.ts`). In comparison, `ts-node` requires installing TypeScript or SWC as peer dependencies.
+
+- **Zero configuration**
+
+	_tsx_ _just works_. It doesn't require initial setup or a `tsconfig.json` file, and doesn't get in the way of running your code. This is especially important for beginners getting into TypeScript!
+
+- **Sensible defaults**
+
+	_tsx_ employs sensible defaults based on file imports and the Node.js version, removing the need for certain `tsconfig.json` settings (that are designed for compilation rather than runtime). In comparison, _ts-node_ relies on TypeScript's defaults (e.g. [`ES3` target](https://www.typescriptlang.org/tsconfig#target)), which may be outdated.
+
+- **Module adaptability**
+
+	_tsx_ automatically adapts between CommonJS and ESM modules, even supporting `require()` of ESM modules, facilitating a smoother transition as the Node.js ecosystem evolves.
+
+- **Enhancements**
+
+	_tsx_ gracefully handles [new JS & TS syntax](https://esbuild.github.io/content-types/) and features based on the Node.js version. It also supports [`tsconfig.json` paths](https://www.typescriptlang.org/tsconfig#paths) out of the box.
+
+- **Speed**
+
+	_tsx_ utilizes [esbuild](https://esbuild.github.io/faq/#:~:text=typescript%20benchmark) for rapid TypeScript compilation. In comparison, _ts-node_ uses the TypeScript compiler by default. Because _tsx_ doesn't type check, it's similar to `ts-node --esm --swc` (which uses the [SWC compiler](https://github.com/TypeStrong/ts-node#swc-1)).
+
+- **Watcher**
+
+	As a DX bonus, _tsx_ also comes with [Watch mode](/watch-mode) to help you iterate faster!
+
+For a detailed technical comparison, you can refer to this [exhaustive comparison](https://github.com/privatenumber/ts-runtime-comparison) between `tsx`, `ts-node`, and other runtimes.
+
+
+## Can/should it be used in production?
+
+At the end of the day, this is something you'll have to evaluate yourself against your production needs and risk tolerance.
+
+Some factors you might want to consider are:
+
+- _tsx_ is Node.js enhanced, so you can expect similar levels of stability.
+
+- _tsx_ uses [esbuild](https://esbuild.github.io) to transform TypeScript and ESM, and esbuild hasn't reached a stable release yet.
+
+
+Some questions you might want to ask yourself are:
+
+- What are the benefits vs costs of using `tsx` in production?
+	- Are there performance costs?
+
+- Does `tsx` run my code expectedly? Are there different environments and tools being used between dev and production?
+
+- Can I rely on this open source project and the maintainers?
+
+## Can't find your question?
+
+Try searching or asking in [GitHub Discussions](https://github.com/privatenumber/tsx/discussions)!

docs/getting-started.md

@@ -0,0 +1,83 @@
+# Getting started
+
+::: info Prerequisites
+You must have [Node.js](https://nodejs.org/) v18 or higher installed. tsx aims to support the [LTS versions](https://endoflife.date/nodejs) of Node.js.
+:::
+
+## Quick try
+
+If you want to try `tsx` without installing it, you can use it with [npx](https://docs.npmjs.com/cli/v8/commands/npx).
+
+In your command-line, simply pass in a TypeScript file you'd like to run:
+
+```sh
+npx tsx ./script.ts
+```
+
+## Installation
+
+### Install to a project
+If you want to add `tsx` as a development dependency to an npm project, `cd` into the project and run the following:
+
+::: code-group
+```sh [npm]
+$ npm install -D tsx
+```
+
+```sh [pnpm]
+$ pnpm install -D tsx
+```
+:::
+
+#### Using `tsx`
+Once installed, you can invoke it with your package manager while in the project directory:
+
+::: code-group
+```sh [npm]
+$ npx tsx ./file.ts
+```
+
+```sh [pnpm]
+$ pnpm tsx ./file.ts
+```
+:::
+
+
+#### Using it in `scripts`
+
+Common commands can be added to [`package.json#scripts`](https://docs.npmjs.com/cli/v10/using-npm/scripts) 
+
+You can reference `tsx` directly in the command like so (you don't need `npx`):
+```json5
+{
+    // ...
+
+    "scripts": {
+        "dev": "tsx ./file.ts"
+    },
+
+    // ...
+}
+```
+
+
+### Install globally
+
+If you want to use `tsx` anywhere on your computer (without [`npx`](https://docs.npmjs.com/cli/v8/commands/npx)), install it globally:
+
+
+::: code-group
+```sh [npm]
+$ npm install -g tsx
+```
+
+```sh [pnpm]
+$ pnpm install -g tsx
+```
+:::
+
+Then, you can call `tsx` directly:
+
+```sh
+tsx file.ts
+```

docs/index.md

@@ -0,0 +1,82 @@
+# What is _tsx_?
+
+`tsx` stands for _TypeScript Execute_, and it's a TypeScript enhanced Node.js.
+
+Because `tsx` is basically an alias to `node`, you can use it the same way:
+
+<div class="tsx-before-after">
+
+```sh
+node file.js
+```
+<span class="hidden sm:block">→</span>
+<span class="sm:hidden">↓</span>
+```sh
+tsx file.js
+```
+</div>
+
+<sub>Since it's Node.js underneath, all command-line flags are supported. Use `tsx` just like you would use `node`!</sub>
+
+## Features
+
+### No hassle TypeScript runner
+
+- _Just run_ [TypeScript](https://www.typescriptlang.org/) code. No configuration required!
+
+	The primary goal of _tsx_ is to run TypeScript code with modern and sensible defaults. This makes _tsx_ very user-friendly and great for beginners!
+
+	<!-- There's also no configuration specifically for _tsx_. Instead, you configure Node.js (via `package.json`) and TypeScript (via `tsconfig.json`). -->
+
+### CJS ↔ ESM interop
+
+- Seamlessly cross-import CommonJS and ES Modules!
+
+	If you've encountered the following error in Node, you'll never see it again with _tsx_!
+
+	```
+	Error [ERR_REQUIRE_ESM]: require() of ES Module <ESM package> from ./file.js not supported.
+	Instead change the require of <ESM package> in ./file.js to a dynamic import() which is available in all CommonJS modules.
+	```
+
+	<sub>This happens in Node.js when importing an ESM file from CommonJS, which can happen in new dependencies.</sub>
+
+### Watch mode
+
+- Iterate on your code faster and boost productivity!
+
+	As a DX bonus, _tsx_ comes with a [watcher](/watch-mode) to re-run your files whenever you save them.
+
+## Limitations
+
+TypeScript & ESM transformations are handled by [esbuild](https://esbuild.github.io/), so it shares some of the same limitations such as:
+
+- Compatibility with `eval()` is not preserved
+- Only [certain `tsconfig.json` properties](https://esbuild.github.io/content-types/#tsconfig-json) are supported
+	- [`emitDecoratorMetadata`](https://www.typescriptlang.org/tsconfig#emitDecoratorMetadata) is not supported
+
+For details, refer to esbuild's [JavaScript caveats](https://esbuild.github.io/content-types/#javascript-caveats) and [TypeScript caveats](https://esbuild.github.io/content-types/#typescript-caveats) documentation.
+
+
+<style scoped>
+.tsx-before-after {
+	@apply
+		flex
+		justify-between
+		gap-4
+		items-center
+		flex-wrap
+		sm:flex-nowrap;
+
+	> * {
+		@apply
+			w-full
+			text-center
+			m-0;
+	}
+
+	> p {
+		@apply sm:w-auto;
+	}
+}
+</style>

docs/node.md

@@ -0,0 +1,51 @@
+---
+outline: deep
+---
+
+# Node.js
+
+## Hooks
+
+> Previously known as _Loaders_ ([renamed in v21](https://github.com/nodejs/loaders/issues/95))
+
+_tsx_ is primarily designed to be a standalone binary used in place of `node`. But sometimes, you'll want to use `node` directly. For example, when adding TypeScript & ESM support to npm-installed binaries that specify node in hashbang.
+
+### Usage
+
+To use `tsx` as a  Node.js loader, pass it in to the [`--import`](https://nodejs.org/api/module.html#enabling) flag. This will add TypeScript & ESM support for both Module and CommonJS contexts.
+
+```sh
+node --import tsx ./file.ts
+```
+
+Or via the [`NODE_OPTIONS`](https://nodejs.org/api/cli.html#node_optionsoptions) environment variable:
+```sh
+NODE_OPTIONS='--import tsx' node ./file.ts
+```
+
+::: warning
+When using the hook, CLI features such as [_Watch mode_](/watch-mode) will not be available.
+:::
+
+
+### ES Modules only
+
+If you only need to add TypeScript support in a Module context, you can use the ESM loader:
+
+##### Node.js v20.6.0 and above
+```sh
+node --import tsx/esm ./file.ts
+```
+
+##### Node.js v20.5.1 and below
+
+```sh
+node --loader tsx/esm ./file.ts
+```
+
+### CommonJS only
+If you only need to add TypeScript & ESM support in a CommonJS context, you can use the CJS loader:
+
+```sh
+node --require tsx/cjs ./file.ts
+```