From ac3b20c368b12ec3ed487193e95008b4764500d1 Mon Sep 17 00:00:00 2001 From: Konrad Reczko Date: Tue, 2 Jun 2026 18:32:33 +0200 Subject: [PATCH 1/2] docs: add TypeGPU tooling guides --- apps/typegpu-docs/astro.config.mjs | 10 +- .../src/content/docs/getting-started.mdx | 8 +- .../src/content/docs/tooling/ai-tools.mdx | 26 ++++ .../src/content/docs/tooling/tgpu-gen.mdx | 18 +-- .../src/content/docs/tooling/typegpu-cli.mdx | 127 ++++++++++++++++++ 5 files changed, 176 insertions(+), 13 deletions(-) create mode 100644 apps/typegpu-docs/src/content/docs/tooling/ai-tools.mdx create mode 100644 apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx diff --git a/apps/typegpu-docs/astro.config.mjs b/apps/typegpu-docs/astro.config.mjs index 24f794d8ad..d2ea6743d6 100644 --- a/apps/typegpu-docs/astro.config.mjs +++ b/apps/typegpu-docs/astro.config.mjs @@ -294,6 +294,10 @@ export default defineConfig({ { label: 'Tooling', items: stripFalsy([ + { + label: 'TypeGPU CLI', + slug: 'tooling/typegpu-cli', + }, { label: 'Build Plugin', slug: 'tooling/unplugin-typegpu', @@ -304,7 +308,11 @@ export default defineConfig({ badge: { text: 'new' }, }, { - label: 'Generator CLI', + label: 'AI Tools', + slug: 'tooling/ai-tools', + }, + { + label: 'WGSL to TypeGPU', slug: 'tooling/tgpu-gen', }, ]), diff --git a/apps/typegpu-docs/src/content/docs/getting-started.mdx b/apps/typegpu-docs/src/content/docs/getting-started.mdx index 675353591f..ae860c1a3d 100644 --- a/apps/typegpu-docs/src/content/docs/getting-started.mdx +++ b/apps/typegpu-docs/src/content/docs/getting-started.mdx @@ -11,6 +11,8 @@ All you need to get started in most cases, is to just run the following command: npx typegpu@latest ``` +For more installation options and existing-project setup, see the [TypeGPU CLI](/TypeGPU/tooling/typegpu-cli) guide. + It allows you to: - Select from a range of **templates** in various frameworks - Pick and choose from our wide variety of **ecosystem packages** @@ -98,10 +100,10 @@ function foo() { We provide a [lint plugin](/TypeGPU/tooling/eslint-plugin-typegpu) that helps with writing 'use gpu' functions. ::: -### AI Tools +:::tip +If you use AI coding agents, see [AI Tools](/TypeGPU/tooling/ai-tools) for the official TypeGPU Skill and runtime inspector MCP. +::: -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. -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. ### Troubleshooting
diff --git a/apps/typegpu-docs/src/content/docs/tooling/ai-tools.mdx b/apps/typegpu-docs/src/content/docs/tooling/ai-tools.mdx new file mode 100644 index 0000000000..0e3acd20ba --- /dev/null +++ b/apps/typegpu-docs/src/content/docs/tooling/ai-tools.mdx @@ -0,0 +1,26 @@ +--- +title: AI Tools +description: A guide to using TypeGPU resources with AI coding agents. +--- + +TypeGPU provides optional tools for AI coding agents working with TypeGPU projects. +They help agents find TypeGPU-specific guidance and inspect generated shader code while debugging. + +## TypeGPU Skill + +The official TypeGPU Skill gives agents guidance for TypeGPU schemas, functions, shaders, buffers, textures, pipelines, and common error patterns. + +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. + +:::tip +The TypeGPU project starter can install the skill for you. Run `npx typegpu@latest` and enable AI skills when prompted. +For a non-interactive setup, run `npx typegpu@latest my-app --yes --agent-skills`. +For an existing project, run `npx typegpu@latest --enhance --yes --agent-skills`. +::: + +## TypeGPU MCP + +The experimental [TypeGPU Runtime Inspector MCP](https://www.npmjs.com/package/typegpu-runtime-inspector-mcp) exposes runtime inspection data to agent tools. +It helps agents catch runtime errors and inspect generated WGSL code alongside other useful TypeGPU runtime information. + +Use it when your agent environment supports MCP servers and you want runtime feedback while iterating on TypeGPU programs. diff --git a/apps/typegpu-docs/src/content/docs/tooling/tgpu-gen.mdx b/apps/typegpu-docs/src/content/docs/tooling/tgpu-gen.mdx index 9491460808..e4ad431695 100644 --- a/apps/typegpu-docs/src/content/docs/tooling/tgpu-gen.mdx +++ b/apps/typegpu-docs/src/content/docs/tooling/tgpu-gen.mdx @@ -1,15 +1,15 @@ --- -title: Generator CLI -description: A guide on how to use the TypeGPU Generator CLI +title: WGSL to TypeGPU +description: Convert existing WGSL shader files into TypeGPU definitions with tgpu-gen. --- import { FileTree } from '@astrojs/starlight/components'; import FileDiff from '../../../components/FileDiff.astro'; -TypeGPU Generator (tgpu-gen) is a CLI companion tool that transforms WGSL code files into +`tgpu-gen` is a WGSL migration tool that transforms WGSL code files into matching TypeGPU definitions. It can be used for integrating TypeGPU into established WebGPU projects, or automating the migration process. -- ✨ Generate TypeGPU definitions from WGSL shaders +- ✨ Convert WGSL shaders into TypeGPU definitions - 👀 Continuously watch for changes in WGSL files and update the generated definitions - 🌲 Specify input and output using glob patterns - 🎯 Choose the output extension and CJS or ESM format @@ -179,7 +179,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; If we wanted to leverage TypeGPU's type-safe features with these shaders, we could manually create the necessary definitions. However, maintaining these handcrafted definitions in sync with the shaders can be both tedious and prone to errors. -Fortunately, we don't have to do that; we can use the TypeGPU Generator CLI to automatically generate the required TypeScript definitions for us. +Fortunately, we don't have to do that; we can use `tgpu-gen` to automatically generate the required TypeScript definitions for us. Assuming that we are inside the project directory (computeBoids folder), we can run the following command to generate the TypeScript definitions for the shaders: @@ -272,7 +272,7 @@ For specific usage details, check out the following Usage section. ## Usage -This section will cover the most common use cases of the TypeGPU Generator CLI and provide short examples. +This section covers the most common `tgpu-gen` use cases and provides short examples. ### Generate TypeGPU definitions for WGSL shader files @@ -304,7 +304,7 @@ The quotes are not necessary if the path does not contain spaces. However, using If you are using glob patterns, quotes are required to prevent the shell from expanding them. ::: -TypeGPU Generator CLI supports glob patterns for specifying input paths. +`tgpu-gen` supports glob patterns for specifying input paths. The following command will generate TypeGPU definitions for all WGSL files inside a given directory: ```bash @@ -526,7 +526,7 @@ This will overwrite the existing TypeScript files with the new TypeGPU definitio ### Watch mode -TypeGPU Generator CLI supports a watch mode that continuously monitors the input files for changes and updates the generated definitions. +`tgpu-gen` supports a watch mode that continuously monitors the input files for changes and updates the generated definitions. To enable the watch mode, use the `--watch` (or `-w`) option: ```bash @@ -539,7 +539,7 @@ By default, the watch mode will overwrite the existing files when changes are de You can also use the `--keep` and `--overwrite` options in the watch mode. They will only affect the initial generation. -## Getting help with the Generator CLI +## Getting help with tgpu-gen To get a quick overview of the generator, its arguments and options, run: diff --git a/apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx b/apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx new file mode 100644 index 0000000000..0d853796aa --- /dev/null +++ b/apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx @@ -0,0 +1,127 @@ +--- +title: TypeGPU CLI +description: Create a TypeGPU project or add TypeGPU to an existing project with npx typegpu@latest. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +The TypeGPU CLI is the project starter for TypeGPU. +Use it to scaffold a new TypeGPU project or enhance an existing project with TypeGPU dependencies and setup. + +## Creating a project + +Run the CLI in the directory where you want to create your project: + + + + ```sh frame=none + npx typegpu@latest + ``` + + + ```sh frame=none + pnpm dlx typegpu@latest + ``` + + + ```sh frame=none + yarn dlx typegpu@latest + ``` + + + ```sh frame=none + bunx typegpu@latest + ``` + + + +The CLI lets you choose a project name and one of the available templates: + +- Vite +- Vite with a more complete TypeGPU example +- Vite + React +- Expo React Native + +It can also install dependencies and download the official TypeGPU AI skill during setup. + +### Non-interactive creation + +Use `--yes` to skip prompts and use defaults: + +```sh +npx typegpu@latest my-app --yes +``` + +You can still select the important setup choices explicitly: + +```sh +npx typegpu@latest my-app --yes --template vite-react --packages @typegpu/sdf --packages @typegpu/noise +``` + +`--yes` skips dependency installation. +Use `--agent-skills` when you want the TypeGPU AI skill installed during project creation: + +```sh +npx typegpu@latest my-app --yes --agent-skills +``` + +## Enhancing an existing project + +Run the CLI with `--enhance` from the root of an existing project: + + + + ```sh frame=none + npx typegpu@latest --enhance + ``` + + + ```sh frame=none + pnpm dlx typegpu@latest --enhance + ``` + + + ```sh frame=none + yarn dlx typegpu@latest --enhance + ``` + + + ```sh frame=none + bunx typegpu@latest --enhance + ``` + + + +### Non-interactive enhancement + +Use `--recommended` with `--yes` to apply the standard Vite-oriented TypeGPU setup without prompts: + +```sh +npx typegpu@latest --enhance --yes --recommended +``` + +You can also add ecosystem packages or the TypeGPU AI skill in the same pass: + +```sh +npx typegpu@latest --enhance --yes --recommended --packages @typegpu/sdf --agent-skills +``` + +If the CLI cannot detect a package manager, pass `--package-manager npm`, `pnpm`, `yarn`, or `bun`. + +:::caution +Back up your project before running the enhance flow. +The CLI does not provide an automatic rollback. +::: + +## Options + +- `-y`, `--yes`: skip prompts and use defaults. +- `--template `: choose `vite-simple`, `vite-complex`, `vite-react`, or `expo-simple`. +- `--packages `: add a TypeGPU ecosystem package. Repeat the flag to add more. +- `--agent-skills`: download the official TypeGPU AI skill. +- `--package-manager `: choose the package manager for dependency and skill commands. +- `--recommended`: use the recommended enhance setup. + +## Related tools + +If you want to convert existing WGSL shader files into TypeGPU definitions, use [tgpu-gen](/TypeGPU/tooling/tgpu-gen) instead. From 8f10cbfe788ce9278583f2d2fd3b22e7cd5af9bf Mon Sep 17 00:00:00 2001 From: Konrad Reczko Date: Wed, 3 Jun 2026 14:17:51 +0200 Subject: [PATCH 2/2] review changes --- apps/typegpu-docs/astro.config.mjs | 2 ++ apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/apps/typegpu-docs/astro.config.mjs b/apps/typegpu-docs/astro.config.mjs index d2ea6743d6..85ccc5184b 100644 --- a/apps/typegpu-docs/astro.config.mjs +++ b/apps/typegpu-docs/astro.config.mjs @@ -297,6 +297,7 @@ export default defineConfig({ { label: 'TypeGPU CLI', slug: 'tooling/typegpu-cli', + badge: { text: 'new' }, }, { label: 'Build Plugin', @@ -310,6 +311,7 @@ export default defineConfig({ { label: 'AI Tools', slug: 'tooling/ai-tools', + badge: { text: 'new' }, }, { label: 'WGSL to TypeGPU', diff --git a/apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx b/apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx index 0d853796aa..8c7be949ce 100644 --- a/apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx +++ b/apps/typegpu-docs/src/content/docs/tooling/typegpu-cli.mdx @@ -38,9 +38,9 @@ Run the CLI in the directory where you want to create your project: The CLI lets you choose a project name and one of the available templates: - Vite -- Vite with a more complete TypeGPU example - Vite + React - Expo React Native +- ... and more It can also install dependencies and download the official TypeGPU AI skill during setup.