diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index eb8c7b2092..d3631e076d 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -221,6 +221,11 @@ export default withNextra({
destination: "/guides/extending-a-world",
permanent: false,
},
+ {
+ source: "/templates/typescript/getting-started",
+ destination: "/quickstart",
+ permanent: false,
+ },
];
},
});
diff --git a/docs/pages/quickstart.mdx b/docs/pages/quickstart.mdx
index 7de324088b..e1f456b25c 100644
--- a/docs/pages/quickstart.mdx
+++ b/docs/pages/quickstart.mdx
@@ -1,20 +1,241 @@
-# Quickstart
+import { Callout } from "nextra/components";
+import { Tabs, Tab } from "nextra/components";
-The easiest way to get started with MUD is to use [a template](/templates/typescript/getting-started).
+# Getting started
-1. Ensure you have [node](https://nodejs.org/en/download/package-manager#macos) 18+, [pnpm](https://pnpm.io/installation) 8+ and [foundry](https://getfoundry.sh/) installed.
-1. Create a new app from a template:
+In most cases the easiest way to get started is to use
+[the TypeScript templates](https://github.com/latticexyz/mud/tree/main/templates) provided by [Lattice](https://lattice.xyz/).
+
+## Prerequisites
+
+To install the TypeScript templates you need:
+
+- [Node.js v18](https://nodejs.org/en/download/package-manager).
+ Note that version 18 is _required_.
+ We do not support older or newer versions at the moment.
+
+
+
+ Installation instructions
+
+
+
+ ```sh copy
+ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 18
+ ```
+
+
+
+ ```powershell copy
+ # installs Chocolatey (Windows Package Manager)
+ Set-ExecutionPolicy Bypass -Scope Process -Force;
+ [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
+ iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'));
+
+ # download and install Node.js
+ choco install nodejs --version="18.19.1"
+ ```
+
+
+
+
+
+- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+
+
+
+ {" "}
+
+ Installation instructions
+
+ {" "}
+
+
+ ```sh copy sudo dnf install git-all ```
+ ```sh copy sudo apt install git-all ```
+ ```sh copy brew install git ```
+ ```powershell copy choco install git ```
+
+
+
+
+- [Foundry](https://book.getfoundry.sh/getting-started/installation)
+
+
+
+ {" "}
+
+ Installation instructions
+
+
+
+
+ ```sh copy
+ curl -L https://foundry.paradigm.xyz | bash export PATH=$PATH:~/.foundry/bin
+ ```
+
+
+
+ 1. Use either Git Bash (which you should already have because you installed git) or [WSL](https://learn.microsoft.com/en-us/windows/wsl/install).
+
+ 1. Run the same commands you would on Linux and MacOS:
+
+ ```sh copy
+ curl -L https://foundry.paradigm.xyz | bash
+ export PATH=$PATH:~/.foundry/bin
+ ```
+
+
+
+
+
+
+
+- [pnpm, at least version 8](https://pnpm.io/)
+
+
+
+ Installation instructions
+
+ ```sh copy
+ sudo npm install -g pnpm
+ ```
+
+
+
+## Installation
+
+To run any of the TypeScript templates:
+
+1. Create the template with pnpm.
+ If you need, replace `tutorial` with your application name.
```sh copy
- pnpm create mud@next my-project
+ pnpm create mud tutorial
```
-1. Start the app:
+
+
+ Possible errors in this stage
+
+ - `ERROR No package.json (or package.yaml, or package.json5) was found in "/home/qbzzt1"`
+
+ `pnpm` version too old.
+ Run `sudo npm install -g pnpm` to update to the latest.
+
+ - `ENOENT ENOENT: no such file or directory, mkdir`
+
+ Out of disk space.
+
+ - `foundryup: need 'git' (command not found)`
+
+ Install [`git`](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+
+ - `SyntaxError: Unexpected token '?'`
+
+ `pnpm` version too old.
+ Run `sudo npm install -g pnpm` to update to the latest.
+
+ - `tutorial is not empty directory.`
+
+ The tutorial needs to be installed in an empty directory.
+ Either delete the directory and its content (`rm -rf tutorial`) or use a different directory.
+
+
+
+1. Select the template:
+
+ - [Vanilla](./vanilla)
+ - [React-ECS](./react-ecs)
+ - React
+ - [Phaser](./phaser)
+ - [Three.js](./three)
+
+1. Start the development server, which updates automatically when you modify files.
```sh copy
- cd my-project
+ cd tutorial
pnpm dev
```
-1. Browse to the application.
- Usually it is at [http://localhost:3000](http://localhost:3000), but if that port is in use it might be 3001, 3002, etc.
+ You can use the arrow keys to move between the logs for the `contracts` package and the logs for the `client` package.
+
+ You can press **Q** to quit `pnpm dev`.
+ If that doesn't work, press **Ctrl-A** and then **Q**.
+
+
+
+ Possible errors in this stage
+
+ - `error binding to 127.0.0.1:8545: error creating server listener: Address already in use`
+
+ [Foundry's `anvil`](https://book.getfoundry.sh/anvil/) is already running, possibly inside a different `pnpm dev`.
+
+ On Linux you can use `sudo netstat -anpe | grep 8545 | grep LISTEN` to get the anvil process ID.
+ You can stop the `anvil` process listening on port 8545 using this command.
+
+ ```sh copy
+ kill `sudo netstat -anpe | grep 8545 | grep LISTEN | awk '{print $9}' | sed 's/\/anvil//'`
+ ```
+
+ Alternatively, a different Ethereum client such as [Geth](https://geth.ethereum.org/) or [Reth](https://paradigmxyz.github.io/reth/intro.html) might be running.
+ As those can be production clients, it is best not to develop on a machine that runs them.
+
+ - `[vite] Internal server error: Failed to resolve import "contracts/out/IWorld.sol/IWorld.abi.json" from "src/mud/setupNetwork.ts"`
+
+ Ignore it.
+ It simply means the `contracts` package hasn't created the `IWorld.abi.json` file, which the `client` package needs, yet.
+ As soon as it is created, the `client` package will use it.
+
+ - `Waiting for localhost:8545......`
+
+ This error happens when `anvil` isn't up yet.
+ If it persists, check the `contracts` package.
+
+
+
+ If nothing else works, the problem may be with [`mprocs`](https://github.com/pvolok/mprocs).
+ We can bypass `mprocs` by running two separate command line windows.
+
+ 1. In the first command line window run these commands to start the client:
+
+ ```sh copy
+ cd packages/client
+ pnpm dev
+ ```
+
+ 1. In the second command line window run these commands to compile the contracts and start `anvil`:
+
+ ```sh copy
+ cd packages/contracts
+ forge || export PATH=$PATH:~/.foundry/bin;
+ pnpm dev
+ ```
+
+
+
+
+
+1. Browse to [`http://127.0.0.1:3000`](http://127.0.0.1:3000).
+ If port 3000 is occupied then the front-end package, [Vite](https://vitejs.dev/), will try to listen to port 3001, then 3002, etc.
+
+## Using the templates
+
+### Code organization
+
+Other than a few utility files, most of the code is in two packages:
+
+- `packages/contracts` contains the onchain part of the application.
+- `packages/client` contains the offchain part of the application, the user interface.
+ The app runs in the user's browser, in development it is served from a [vite](https://vitejs.dev/) server.
+ The content of this package varies based on the template used.
+
+### Vanilla and react-ecs
+
+The applications in these two templates is the same.
+You have an onchain counter and you can press `Increment` to increment it.
+
+### Three.js
+
+In this application the position of an object, the big green cube, is stored onchain.
+In the user interface you can move that cube using the arrow keys, space, and ctrl.
diff --git a/docs/pages/templates/typescript/_meta.js b/docs/pages/templates/typescript/_meta.js
index 536ee8b368..2d12804a73 100644
--- a/docs/pages/templates/typescript/_meta.js
+++ b/docs/pages/templates/typescript/_meta.js
@@ -1,5 +1,4 @@
export default {
- "getting-started": "Getting Started",
contracts: "Contracts",
vanilla: "Vanilla",
"react-ecs": "React-ECS",
diff --git a/docs/pages/templates/typescript/getting-started.mdx b/docs/pages/templates/typescript/getting-started.mdx
deleted file mode 100644
index 964ef66c93..0000000000
--- a/docs/pages/templates/typescript/getting-started.mdx
+++ /dev/null
@@ -1,74 +0,0 @@
-# Getting started
-
-[The TypeScript templates](https://github.com/latticexyz/mud/tree/main/templates) are provided by [Lattice](https://lattice.xyz/).
-
-## Prerequisites
-
-To install the TypeScript templates you need:
-
-- [Node.js v18](https://nodejs.org/en/download/package-manager)
-- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-- [Foundry](https://book.getfoundry.sh/getting-started/installation)
-- [pnpm](https://pnpm.io/)
- ```sh copy
- sudo npm install -g pnpm
- ```
-
-## Installation
-
-To run any of the TypeScript templates:
-
-1. Create the template with pnpm.
- If you need, replace `tutorial` with your application name.
-
- ```sh copy
- pnpm create mud@next tutorial
- ```
-
- **Note:** The `@next` is only necessary until MUD v2.0 is officially released.
-
-1. Select the template:
-
- - [Vanilla](./vanilla)
- - [React-ECS](./react-ecs)
- - React
- - [Phaser](./phaser)
- - [Three.js](./three)
-
-1. Start the development server, which updates automatically when you modify files.
-
- ```sh copy
- cd tutorial
- pnpm dev
- ```
-
- You may receive this error message:
-
- ```
- [vite] Internal server error: Failed to resolve import "contracts/out/IWorld.sol/IWorld.abi.json" from "src/mud/setupNetwork.ts"
- ```
-
- If so, ignore it.
- It simply means the `contracts` package hasn't created the `IWorld.abi.json` file, which the `client` package needs, yet.
- As soon as it is created, the `client` package will use it.
-
-## Using the templates
-
-### Code organization
-
-Other than a few utility files, most of the code is in two packages:
-
-- `packages/contracts` contains the onchain part of the application.
-- `packages/client` contains the offchain part of the application, the user interface.
- The app runs in the user's browser, in development it is served from a [vite](https://vitejs.dev/) server.
- The content of this package varies based on the template used.
-
-### Vanilla and react-ecs
-
-The applications in these two templates is the same.
-You have an onchain counter and you can press `Increment` to increment it.
-
-### Three.js
-
-In this application the position of an object, the big green cube, is stored onchain.
-In the user interface you can move that cube using the arrow keys, space, and ctrl.