Skip to content

Commit

Permalink
docs: refine TS guides
Browse files Browse the repository at this point in the history
  • Loading branch information
antongolub committed May 11, 2024
1 parent e7485e8 commit 759498d
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 12 deletions.
1 change: 1 addition & 0 deletions setup.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Setup

## Requirements
* Linux, macOS, or Windows
* JavaScript Runtime:
* Node.js 12.17.0 or later
* Bun 1.0.0 or later
Expand Down
55 changes: 43 additions & 12 deletions typescript.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,59 @@
# TypeScript

Configure your project to use [ES modules](https://nodejs.org/api/packages.html#packages_type):
zx is written in TypeScript and provides the corresponding libdefs out of box. Typings are TS 4+ compatible.

```ts
// script.ts
import { $ } from 'zx'

const list = await $`ls -la`
```

Some runtimes like [Bun](https://bun.sh/) or [Deno](https://deno.com/) have built-in TS support, so you can use zx directly. Node.js requires additional setup. Configure your project according to the [ES modules contract](https://nodejs.org/api/packages.html#packages_type):

- Set [`"type": "module"`](https://nodejs.org/api/packages.html#packages_type)
in **package.json**
- Set [`"module": "ESNext"`](https://www.typescriptlang.org/tsconfig/#module)
in **tsconfig.json**.

It is possible to make use of `$` and other functions via explicit imports:
Using TypeScript compiler is the most straightforward way.

```ts
import { $ } from 'zx'
::: code-group

```bash [tsc]
npm install typescript

tsc script.ts

node script.js
```

Or import globals explicitly:
```bash [ts-node]
npm install ts-node

```ts
import 'zx/globals'
ts-node script.ts
# or via node loader
node --loader ts-node/esm script.ts
```

Wrap your code in an async function and call it immediately:
```bash [swc-node]
npm install swc-node

```ts
void async function () {
await $`ls -la`
}()
swc-node script.ts
```

```bash [tsx]
npm install tsx

tsx script.ts
```

```bash [bun]
bun script.ts
```

```bash [deno]
deno run --allow-read --allow-sys --allow-env --allow-run script.ts
```

:::

0 comments on commit 759498d

Please sign in to comment.