Skip to content

Commit ac3b20c

Browse files
reczkokreczkok
committed
docs: add TypeGPU tooling guides
1 parent 9cd2230 commit ac3b20c

5 files changed

Lines changed: 176 additions & 13 deletions

File tree

‎apps/typegpu-docs/astro.config.mjs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,10 @@ export default defineConfig({
294294
{
295295
label: 'Tooling',
296296
items: stripFalsy([
297+
{
298+
label: 'TypeGPU CLI',
299+
slug: 'tooling/typegpu-cli',
300+
},
297301
{
298302
label: 'Build Plugin',
299303
slug: 'tooling/unplugin-typegpu',
@@ -304,7 +308,11 @@ export default defineConfig({
304308
badge: { text: 'new' },
305309
},
306310
{
307-
label: 'Generator CLI',
311+
label: 'AI Tools',
312+
slug: 'tooling/ai-tools',
313+
},
314+
{
315+
label: 'WGSL to TypeGPU',
308316
slug: 'tooling/tgpu-gen',
309317
},
310318
]),

‎apps/typegpu-docs/src/content/docs/getting-started.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ All you need to get started in most cases, is to just run the following command:
1111
npx typegpu@latest
1212
```
1313

14+
For more installation options and existing-project setup, see the [TypeGPU CLI](/TypeGPU/tooling/typegpu-cli) guide.
15+
1416
It allows you to:
1517
- Select from a range of **templates** in various frameworks
1618
- Pick and choose from our wide variety of **ecosystem packages**
@@ -98,10 +100,10 @@ function foo() {
98100
We provide a [lint plugin](/TypeGPU/tooling/eslint-plugin-typegpu) that helps with writing 'use gpu' functions.
99101
:::
100102

101-
### AI Tools
103+
:::tip
104+
If you use AI coding agents, see [AI Tools](/TypeGPU/tooling/ai-tools) for the official TypeGPU Skill and runtime inspector MCP.
105+
:::
102106

103-
To install the official TypeGPU Skill, head to the [Software Mansion Skills repository](https://github.com/software-mansion-labs/skills) and select the TypeGPU skill during the setup process.
104-
You can also use the experimental [TypeGPU MCP](https://www.npmjs.com/package/typegpu-runtime-inspector-mcp) to make it easier for agents to catch runtime errors and inspect the generated WGSL code along with other useful runtime information.
105107
### Troubleshooting
106108

107109
<details>

‎apps/typegpu-docs/src/content/docs/tooling/ai-tools.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: AI Tools
3+
description: A guide to using TypeGPU resources with AI coding agents.
4+
---
5+
6+
TypeGPU provides optional tools for AI coding agents working with TypeGPU projects.
7+
They help agents find TypeGPU-specific guidance and inspect generated shader code while debugging.
8+
9+
## TypeGPU Skill
10+
11+
The official TypeGPU Skill gives agents guidance for TypeGPU schemas, functions, shaders, buffers, textures, pipelines, and common error patterns.
12+
13+
To install it, use the [Software Mansion Skills repository](https://github.com/software-mansion-labs/skills) and select the TypeGPU skill during the setup process.
14+
15+
:::tip
16+
The TypeGPU project starter can install the skill for you. Run `npx typegpu@latest` and enable AI skills when prompted.
17+
For a non-interactive setup, run `npx typegpu@latest my-app --yes --agent-skills`.
18+
For an existing project, run `npx typegpu@latest --enhance --yes --agent-skills`.
19+
:::
20+
21+
## TypeGPU MCP
22+
23+
The experimental [TypeGPU Runtime Inspector MCP](https://www.npmjs.com/package/typegpu-runtime-inspector-mcp) exposes runtime inspection data to agent tools.
24+
It helps agents catch runtime errors and inspect generated WGSL code alongside other useful TypeGPU runtime information.
25+
26+
Use it when your agent environment supports MCP servers and you want runtime feedback while iterating on TypeGPU programs.

‎apps/typegpu-docs/src/content/docs/tooling/tgpu-gen.mdx‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
---
2-
title: Generator CLI
3-
description: A guide on how to use the TypeGPU Generator CLI
2+
title: WGSL to TypeGPU
3+
description: Convert existing WGSL shader files into TypeGPU definitions with tgpu-gen.
44
---
55

66
import { FileTree } from '@astrojs/starlight/components';
77
import FileDiff from '../../../components/FileDiff.astro';
88

9-
TypeGPU Generator (tgpu-gen) is a CLI companion tool that transforms WGSL code files into
9+
`tgpu-gen` is a WGSL migration tool that transforms WGSL code files into
1010
matching TypeGPU definitions. It can be used for integrating TypeGPU into established WebGPU projects, or automating the migration process.
1111

12-
- ✨ Generate TypeGPU definitions from WGSL shaders
12+
- ✨ Convert WGSL shaders into TypeGPU definitions
1313
- 👀 Continuously watch for changes in WGSL files and update the generated definitions
1414
- 🌲 Specify input and output using glob patterns
1515
- 🎯 Choose the output extension and CJS or ESM format
@@ -179,7 +179,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
179179
If we wanted to leverage TypeGPU's type-safe features with these shaders, we could
180180
manually create the necessary definitions. However, maintaining these handcrafted
181181
definitions in sync with the shaders can be both tedious and prone to errors.
182-
Fortunately, we don't have to do that; we can use the TypeGPU Generator CLI to automatically generate the required TypeScript definitions for us.
182+
Fortunately, we don't have to do that; we can use `tgpu-gen` to automatically generate the required TypeScript definitions for us.
183183

184184
Assuming that we are inside the project directory (computeBoids folder), we can run the following command to generate the TypeScript definitions for the shaders:
185185

@@ -272,7 +272,7 @@ For specific usage details, check out the following Usage section.
272272

273273
## Usage
274274

275-
This section will cover the most common use cases of the TypeGPU Generator CLI and provide short examples.
275+
This section covers the most common `tgpu-gen` use cases and provides short examples.
276276

277277
### Generate TypeGPU definitions for WGSL shader files
278278

@@ -304,7 +304,7 @@ The quotes are not necessary if the path does not contain spaces. However, using
304304
If you are using glob patterns, quotes are required to prevent the shell from expanding them.
305305
:::
306306

307-
TypeGPU Generator CLI supports glob patterns for specifying input paths.
307+
`tgpu-gen` supports glob patterns for specifying input paths.
308308
The following command will generate TypeGPU definitions for all WGSL files inside a given directory:
309309

310310
```bash
@@ -526,7 +526,7 @@ This will overwrite the existing TypeScript files with the new TypeGPU definitio
526526

527527
### Watch mode
528528

529-
TypeGPU Generator CLI supports a watch mode that continuously monitors the input files for changes and updates the generated definitions.
529+
`tgpu-gen` supports a watch mode that continuously monitors the input files for changes and updates the generated definitions.
530530
To enable the watch mode, use the `--watch` (or `-w`) option:
531531

532532
```bash
@@ -539,7 +539,7 @@ By default, the watch mode will overwrite the existing files when changes are de
539539
You can also use the `--keep` and `--overwrite` options in the watch mode. They will only affect the initial generation.
540540

541541

542-
## Getting help with the Generator CLI
542+
## Getting help with tgpu-gen
543543

544544
To get a quick overview of the generator, its arguments and options, run:
545545

‎apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: TypeGPU CLI
3+
description: Create a TypeGPU project or add TypeGPU to an existing project with npx typegpu@latest.
4+
---
5+
6+
import { Tabs, TabItem } from '@astrojs/starlight/components';
7+
8+
The TypeGPU CLI is the project starter for TypeGPU.
9+
Use it to scaffold a new TypeGPU project or enhance an existing project with TypeGPU dependencies and setup.
10+
11+
## Creating a project
12+
13+
Run the CLI in the directory where you want to create your project:
14+
15+
<Tabs syncKey="package-manager">
16+
<TabItem label="npm" icon="seti:npm">
17+
```sh frame=none
18+
npx typegpu@latest
19+
```
20+
</TabItem>
21+
<TabItem label="pnpm" icon="pnpm">
22+
```sh frame=none
23+
pnpm dlx typegpu@latest
24+
```
25+
</TabItem>
26+
<TabItem label="yarn" icon="seti:yarn">
27+
```sh frame=none
28+
yarn dlx typegpu@latest
29+
```
30+
</TabItem>
31+
<TabItem label="bun" icon="bun">
32+
```sh frame=none
33+
bunx typegpu@latest
34+
```
35+
</TabItem>
36+
</Tabs>
37+
38+
The CLI lets you choose a project name and one of the available templates:
39+
40+
- Vite
41+
- Vite with a more complete TypeGPU example
42+
- Vite + React
43+
- Expo React Native
44+
45+
It can also install dependencies and download the official TypeGPU AI skill during setup.
46+
47+
### Non-interactive creation
48+
49+
Use `--yes` to skip prompts and use defaults:
50+
51+
```sh
52+
npx typegpu@latest my-app --yes
53+
```
54+
55+
You can still select the important setup choices explicitly:
56+
57+
```sh
58+
npx typegpu@latest my-app --yes --template vite-react --packages @typegpu/sdf --packages @typegpu/noise
59+
```
60+
61+
`--yes` skips dependency installation.
62+
Use `--agent-skills` when you want the TypeGPU AI skill installed during project creation:
63+
64+
```sh
65+
npx typegpu@latest my-app --yes --agent-skills
66+
```
67+
68+
## Enhancing an existing project
69+
70+
Run the CLI with `--enhance` from the root of an existing project:
71+
72+
<Tabs syncKey="package-manager">
73+
<TabItem label="npm" icon="seti:npm">
74+
```sh frame=none
75+
npx typegpu@latest --enhance
76+
```
77+
</TabItem>
78+
<TabItem label="pnpm" icon="pnpm">
79+
```sh frame=none
80+
pnpm dlx typegpu@latest --enhance
81+
```
82+
</TabItem>
83+
<TabItem label="yarn" icon="seti:yarn">
84+
```sh frame=none
85+
yarn dlx typegpu@latest --enhance
86+
```
87+
</TabItem>
88+
<TabItem label="bun" icon="bun">
89+
```sh frame=none
90+
bunx typegpu@latest --enhance
91+
```
92+
</TabItem>
93+
</Tabs>
94+
95+
### Non-interactive enhancement
96+
97+
Use `--recommended` with `--yes` to apply the standard Vite-oriented TypeGPU setup without prompts:
98+
99+
```sh
100+
npx typegpu@latest --enhance --yes --recommended
101+
```
102+
103+
You can also add ecosystem packages or the TypeGPU AI skill in the same pass:
104+
105+
```sh
106+
npx typegpu@latest --enhance --yes --recommended --packages @typegpu/sdf --agent-skills
107+
```
108+
109+
If the CLI cannot detect a package manager, pass `--package-manager npm`, `pnpm`, `yarn`, or `bun`.
110+
111+
:::caution
112+
Back up your project before running the enhance flow.
113+
The CLI does not provide an automatic rollback.
114+
:::
115+
116+
## Options
117+
118+
- `-y`, `--yes`: skip prompts and use defaults.
119+
- `--template <name>`: choose `vite-simple`, `vite-complex`, `vite-react`, or `expo-simple`.
120+
- `--packages <name>`: add a TypeGPU ecosystem package. Repeat the flag to add more.
121+
- `--agent-skills`: download the official TypeGPU AI skill.
122+
- `--package-manager <pm>`: choose the package manager for dependency and skill commands.
123+
- `--recommended`: use the recommended enhance setup.
124+
125+
## Related tools
126+
127+
If you want to convert existing WGSL shader files into TypeGPU definitions, use [tgpu-gen](/TypeGPU/tooling/tgpu-gen) instead.

0 commit comments

Comments
 (0)