docs(quickstart): update, add common errors and prereq installation (#…

…2459)

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,
+      },
     ];
   },
 });

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.
+
+    <details>
+
+      <summary>Installation instructions</summary>
+
+      <Tabs items={["Linux and MacOS", "Windows"]}>
+        <Tab>
+          ```sh copy
+          curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 18
+          ```
+        </Tab>
+
+        <Tab>
+        ```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"
+          ```
+        </Tab>
+      </Tabs>
+
+    </details>
+
+- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+
+  <details>
+
+  {" "}
+
+  <summary>Installation instructions</summary>
+
+  {" "}
+
+  <Tabs items={["Linux (RedHat based)", "Linux (Debian based)", "MacOS", "Windows"]}>
+    <Tab>```sh copy sudo dnf install git-all ```</Tab>
+    <Tab>```sh copy sudo apt install git-all ```</Tab>
+    <Tab>```sh copy brew install git ```</Tab>
+    <Tab>```powershell copy choco install git ```</Tab>
+  </Tabs>
+
+  </details>
+
+- [Foundry](https://book.getfoundry.sh/getting-started/installation)
+
+  <details>
+
+  {" "}
+
+  <summary>Installation instructions</summary>
+
+    <Tabs items={['Linux and MacOS', 'Windows']}>
+
+      <Tab>
+        ```sh copy
+        curl -L https://foundry.paradigm.xyz | bash export PATH=$PATH:~/.foundry/bin
+        ```
+      </Tab>
+
+      <Tab>
+        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
+           ```
+
+      </Tab>
+
+    </Tabs>
+
+  </details>
+
+- [pnpm, at least version 8](https://pnpm.io/)
+
+    <details>
+
+      <summary>Installation instructions</summary>
+
+      ```sh copy
+      sudo npm install -g pnpm
+      ```
+
+    </details>
+
+## 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:
+   <details>
+
+   <summary>Possible errors in this stage</summary>
+
+   - `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.
+
+   </details>
+
+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**.
+
+   <details>
+
+   <summary>Possible errors in this stage</summary>
+
+   - `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.
+
+   <Callout type="info" emoji="ⓘ">
+
+   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
+      ```
+
+   </Callout>
+
+   </details>
+
+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.

docs/pages/templates/typescript/_meta.js

@@ -1,5 +1,4 @@
 export default {
-  "getting-started": "Getting Started",
   contracts: "Contracts",
   vanilla: "Vanilla",
   "react-ecs": "React-ECS",