From ab9bcead34c1eaab2a1c68143559c90df49e8e41 Mon Sep 17 00:00:00 2001 From: Exelo Date: Sun, 14 Jun 2026 15:40:15 +0900 Subject: [PATCH] docs: add full cli docs and guides --- docs.json | 4 - docs/docs/commands/1-overview.mdx | 54 ++++++ docs/docs/commands/2-commands/1-new.mdx | 54 ++++++ docs/docs/commands/2-commands/2-dev.mdx | 37 ++++ docs/docs/commands/2-commands/3-build.mdx | 45 +++++ docs/docs/commands/2-commands/4-start.mdx | 51 +++++ docs/docs/commands/2-commands/5-generate.mdx | 39 ++++ docs/docs/commands/2-commands/6-create.mdx | 42 ++++ docs/docs/commands/2-commands/7-install.mdx | 46 +++++ docs/docs/commands/2-commands/8-editor.mdx | 39 ++++ docs/docs/commands/2-commands/9-registry.mdx | 65 +++++++ .../configuration/1-configuration-file.mdx | 82 ++++++++ .../configuration/2-environment-variables.mdx | 35 ++++ docs/docs/getting-started/1-introduction.mdx | 43 +++++ docs/docs/getting-started/2-installation.mdx | 40 ++++ docs/docs/getting-started/3-quickstart.mdx | 63 ++++++ docs/docs/getting-started/index.mdx | 15 -- docs/docs/getting-started/usage.mdx | 179 ------------------ docs/guides/cli/1-overview.mdx | 28 +++ docs/guides/cli/2-create-a-project.mdx | 51 +++++ docs/guides/cli/3-develop-locally.mdx | 50 +++++ docs/guides/cli/4-build-and-deploy.mdx | 54 ++++++ docs/guides/cli/5-components-and-systems.mdx | 52 +++++ docs/guides/cli/6-publish-a-package.mdx | 43 +++++ 24 files changed, 1013 insertions(+), 198 deletions(-) delete mode 100644 docs.json create mode 100644 docs/docs/commands/1-overview.mdx create mode 100644 docs/docs/commands/2-commands/1-new.mdx create mode 100644 docs/docs/commands/2-commands/2-dev.mdx create mode 100644 docs/docs/commands/2-commands/3-build.mdx create mode 100644 docs/docs/commands/2-commands/4-start.mdx create mode 100644 docs/docs/commands/2-commands/5-generate.mdx create mode 100644 docs/docs/commands/2-commands/6-create.mdx create mode 100644 docs/docs/commands/2-commands/7-install.mdx create mode 100644 docs/docs/commands/2-commands/8-editor.mdx create mode 100644 docs/docs/commands/2-commands/9-registry.mdx create mode 100644 docs/docs/configuration/1-configuration-file.mdx create mode 100644 docs/docs/configuration/2-environment-variables.mdx create mode 100644 docs/docs/getting-started/1-introduction.mdx create mode 100644 docs/docs/getting-started/2-installation.mdx create mode 100644 docs/docs/getting-started/3-quickstart.mdx delete mode 100644 docs/docs/getting-started/index.mdx delete mode 100644 docs/docs/getting-started/usage.mdx create mode 100644 docs/guides/cli/1-overview.mdx create mode 100644 docs/guides/cli/2-create-a-project.mdx create mode 100644 docs/guides/cli/3-develop-locally.mdx create mode 100644 docs/guides/cli/4-build-and-deploy.mdx create mode 100644 docs/guides/cli/5-components-and-systems.mdx create mode 100644 docs/guides/cli/6-publish-a-package.mdx diff --git a/docs.json b/docs.json deleted file mode 100644 index e442b22..0000000 --- a/docs.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "group": "CLI", - "pages": ["docs/cli/index", "docs/cli/usage"] -} diff --git a/docs/docs/commands/1-overview.mdx b/docs/docs/commands/1-overview.mdx new file mode 100644 index 0000000..feff2b4 --- /dev/null +++ b/docs/docs/commands/1-overview.mdx @@ -0,0 +1,54 @@ +--- +title: Commands +description: Overview of every NanoForge CLI command +--- + +import { Card, CardGroup } from "mintlify/components"; + +## Using the CLI + +Every command follows the same shape: + +```bash +nf [command] [options] +``` + +Most commands accept `-d, --directory ` to set the working directory and +`-c, --config ` to point at a specific configuration file. Run any command with `--help` to +see its full option list: + +```bash +nf --help +``` + +## Available commands + + + + Scaffold a brand new NanoForge project. + + + Run your project in development mode with watching. + + + Compile your client and server for production. + + + Serve a built project, optionally over HTTPS. + + + Generate project files from your configuration. + + + Create a single component or system. + + + Add components, systems, or libraries from the registry. + + + Launch the NanoForge visual editor. + + + Authenticate, publish, and unpublish packages. + + diff --git a/docs/docs/commands/2-commands/1-new.mdx b/docs/docs/commands/2-commands/1-new.mdx new file mode 100644 index 0000000..dd11d75 --- /dev/null +++ b/docs/docs/commands/2-commands/1-new.mdx @@ -0,0 +1,54 @@ +--- +title: new +description: Create a new NanoForge project +--- + +## Overview + +`nf new` scaffolds a brand new NanoForge project. Run without flags it is fully interactive, +prompting for everything it needs. Any answer can be supplied up front as a flag to skip the +corresponding prompt. + +## Usage + +```bash +nf new +``` + +## Options + +| Option | Description | +| ---------------------------------------------- | ----------------------------------------------------------------------- | +| `-d, --directory ` | Working directory of the command. | +| `--name ` | Name of your project. | +| `--path ` | Relative path where the project is created (default: the project name). | +| `--package-manager ` | Package manager: `npm`, `yarn`, `pnpm`, or `bun`. | +| `--language ` | Project language: `ts` or `js`. | +| `--strict` / `--no-strict` | Enable or disable strict mode. | +| `--server` / `--no-server` | Generate a server alongside the client. | +| `--init-functions` / `--no-init-functions` | Add lifecycle init functions. | +| `--skip-install` / `--no-skip-install` | Skip installing dependencies after scaffolding. | +| `--docker` / `--no-docker` | Generate Docker files. | +| `--no-lint` | Skip generating lint configuration files. | +| `--editor` | Add editor dependencies. | +| `--git` / `--no-git` | Initialize a git repository. | +| `--git-remote ` / `--no-git-remote` | Set up a git remote (requires `--git`). | + +## Examples + +**Interactive:** + +```bash +nf new +``` + +**Non-interactive TypeScript project with a server:** + +```bash +nf new \ + --name my-game \ + --language ts \ + --package-manager pnpm \ + --server \ + --no-docker +``` diff --git a/docs/docs/commands/2-commands/2-dev.mdx b/docs/docs/commands/2-commands/2-dev.mdx new file mode 100644 index 0000000..7afc7e2 --- /dev/null +++ b/docs/docs/commands/2-commands/2-dev.mdx @@ -0,0 +1,37 @@ +--- +title: dev +description: Run your NanoForge project in development mode +--- + +## Overview + +`nf dev` runs your NanoForge project in development mode. It is the command you keep open while +working — it serves the game and reacts to changes. + +## Usage + +```bash +nf dev +``` + +## Options + +| Option | Description | +| ----------------------------- | ------------------------------------------------------------------------------------------ | +| `-d, --directory ` | Working directory of the command. | +| `-c, --config ` | Path to the configuration file. | +| `--generate` | Generate app files from config in dev mode, like the `generate` command. Default: `false`. | + +## Examples + +**Standard dev run:** + +```bash +nf dev +``` + +**Regenerate files from config while developing:** + +```bash +nf dev --generate +``` diff --git a/docs/docs/commands/2-commands/3-build.mdx b/docs/docs/commands/2-commands/3-build.mdx new file mode 100644 index 0000000..930f210 --- /dev/null +++ b/docs/docs/commands/2-commands/3-build.mdx @@ -0,0 +1,45 @@ +--- +title: build +description: Build your NanoForge project for production +--- + +## Overview + +`nf build` compiles your NanoForge project. The client and server entry points, static directories, +and output directories all default to the values in your +[configuration file](../../configuration/1-configuration-file) and can be overridden per run. + +## Usage + +```bash +nf build +``` + +## Options + +| Option | Description | +| --------------------------------------- | -------------------------------------- | +| `-d, --directory ` | Working directory of the command. | +| `-c, --config ` | Path to the configuration file. | +| `--client-entry ` | Entry file of the client. | +| `--server-entry ` | Entry file of the server. | +| `--client-static-dir ` | Static directory of the client. | +| `--server-static-dir ` | Static directory of the server. | +| `--client-out-dir ` | Output directory of the client. | +| `--server-out-dir ` | Output directory of the server. | +| `--editor` | Build with the editor configuration. | +| `--watch` | Build in watch mode. Default: `false`. | + +## Examples + +**Build using the configuration defaults:** + +```bash +nf build +``` + +**Rebuild on change with a custom client output directory:** + +```bash +nf build --watch --client-out-dir dist/client +``` diff --git a/docs/docs/commands/2-commands/4-start.mdx b/docs/docs/commands/2-commands/4-start.mdx new file mode 100644 index 0000000..1b9e8b2 --- /dev/null +++ b/docs/docs/commands/2-commands/4-start.mdx @@ -0,0 +1,51 @@ +--- +title: start +description: Start a built NanoForge project +--- + +import { Note } from "mintlify/components"; + +## Overview + +`nf start` serves a previously built NanoForge project. It launches the loader (the website that +loads the game) and, when enabled, the server. It can also serve over HTTPS when given a +certificate and key. + +## Usage + +```bash +nf start +``` + +## Options + +| Option | Description | +| -------------------------------- | ----------------------------------------------------------------- | +| `-d, --directory ` | Working directory of the command. | +| `-c, --config ` | Path to the configuration file. Default: `nanoforge.config.json`. | +| `-p, --port ` | Port of the loader (the website that loads the game). | +| `--client-dir ` | Directory of the built client. | +| `--server-dir ` | Directory of the built server. | +| `--watch` | Run in watch mode. Default: `false`. | +| `--cert ` | Path to the SSL certificate for HTTPS. | +| `--key ` | Path to the SSL key for HTTPS. | + +## Examples + +**Start on a custom port:** + +```bash +nf start --port 8080 +``` + +**Start over HTTPS:** + +```bash +nf start --cert ./certs/cert.pem --key ./certs/key.pem +``` + + + Environment variables (for example server addresses and ports) are read from a `.env` file at the + project root when the game starts. See [Environment + variables](../../configuration/2-environment-variables). + diff --git a/docs/docs/commands/2-commands/5-generate.mdx b/docs/docs/commands/2-commands/5-generate.mdx new file mode 100644 index 0000000..831fc97 --- /dev/null +++ b/docs/docs/commands/2-commands/5-generate.mdx @@ -0,0 +1,39 @@ +--- +title: generate +description: Generate NanoForge project files from configuration +--- + +## Overview + +`nf generate` generates project files from your [configuration](../../configuration/1-configuration-file). +It reads the config and produces the entry files and wiring your project needs, including the editor +main file when requested. + +## Usage + +```bash +nf generate +``` + +## Options + +| Option | Description | +| ----------------------------- | ----------------------------------------- | +| `-d, --directory ` | Working directory of the command. | +| `-c, --config ` | Path to the configuration file. | +| `--editor` | Generate the editor main file. | +| `--watch` | Generate in watch mode. Default: `false`. | + +## Examples + +**Generate once:** + +```bash +nf generate +``` + +**Regenerate on change, including the editor entry:** + +```bash +nf generate --editor --watch +``` diff --git a/docs/docs/commands/2-commands/6-create.mdx b/docs/docs/commands/2-commands/6-create.mdx new file mode 100644 index 0000000..e63ebcf --- /dev/null +++ b/docs/docs/commands/2-commands/6-create.mdx @@ -0,0 +1,42 @@ +--- +title: create +description: Create a NanoForge component or system +--- + +## Overview + +`nf create` scaffolds a single ECS **component** or **system** in your project. By default it +creates files for the client; pass `--server` to target the server instead. + +## Usage + +```bash +nf create +``` + +`` is either `component` or `system`. + +## Options + +| Option | Description | +| ----------------------------- | ------------------------------------------------------------- | +| `` | The type to create: `component` or `system`. | +| `-d, --directory ` | Working directory of the command. | +| `-c, --config ` | Path to the configuration file. | +| `-n, --name ` | Name of the component or system. | +| `-s, --server` | Create on the server instead of the client. Default: `false`. | +| `-p, --path ` | Path to the component/system folder. | + +## Examples + +**Create a client component:** + +```bash +nf create component --name Position +``` + +**Create a server system:** + +```bash +nf create system --name Movement --server +``` diff --git a/docs/docs/commands/2-commands/7-install.mdx b/docs/docs/commands/2-commands/7-install.mdx new file mode 100644 index 0000000..f08fccc --- /dev/null +++ b/docs/docs/commands/2-commands/7-install.mdx @@ -0,0 +1,46 @@ +--- +title: install / add +description: Add components, systems, or libraries to your project +--- + +import { Note } from "mintlify/components"; + +## Overview + +`nf install` (aliased as `nf add`) pulls components, systems, or libraries from the NanoForge +registry into your project. By default it installs components and systems for the client; use +`--lib` for libraries and `--server` to target the server. + +## Usage + +```bash +nf install [names...] +``` + +## Options + +| Option | Description | +| ----------------------------- | ------------------------------------------------------------------ | +| `[names...]` | Names of the components/systems/libraries to install. | +| `-d, --directory ` | Working directory of the command. | +| `-l, --lib` | Install a library instead of a component/system. Default: `false`. | +| `-s, --server` | Install on the server instead of the client. Default: `false`. | + +## Examples + +**Install a component for the client:** + +```bash +nf install my-org/health-bar +``` + +**Install a library on the server:** + +```bash +nf add my-org/physics --lib --server +``` + + + Installing from a private scope may require authentication. See the [registry + commands](./9-registry) to log in first. + diff --git a/docs/docs/commands/2-commands/8-editor.mdx b/docs/docs/commands/2-commands/8-editor.mdx new file mode 100644 index 0000000..cc4d957 --- /dev/null +++ b/docs/docs/commands/2-commands/8-editor.mdx @@ -0,0 +1,39 @@ +--- +title: editor +description: Launch the NanoForge visual editor +--- + +## Overview + +`nf editor` starts the NanoForge editor — a visual environment for inspecting and authoring your +game. When a project `path` is given, the editor opens that project; by default it then opens in +your browser. + +## Usage + +```bash +nf editor [path] +``` + +## Options + +| Option | Description | +| ----------------------------- | --------------------------------------------------------------------------------------------- | +| `[path]` | Path to the project to open in the editor. | +| `-d, --directory ` | Working directory of the command. | +| `--open` | Open the editor in the default web browser. Default: `true` when `path` is set, else `false`. | +| `--no-open` | Do not open the editor in the browser. | + +## Examples + +**Open the editor for the current project:** + +```bash +nf editor . +``` + +**Start the editor without opening a browser tab:** + +```bash +nf editor --no-open +``` diff --git a/docs/docs/commands/2-commands/9-registry.mdx b/docs/docs/commands/2-commands/9-registry.mdx new file mode 100644 index 0000000..bba7010 --- /dev/null +++ b/docs/docs/commands/2-commands/9-registry.mdx @@ -0,0 +1,65 @@ +--- +title: registry +description: Authenticate with and publish to the NanoForge registry +--- + +## Overview + +These commands manage your relationship with the NanoForge registry: authenticating, then publishing +or removing packages. Authentication can be **global** (default, stored for your user) or **local** +(scoped to the current project) with `-l, --local`. + +## login + +Log in to the NanoForge registry. + +```bash +nf login +``` + +| Option | Description | +| ----------------------------- | ------------------------------------------------------ | +| `-d, --directory ` | Working directory of the command. | +| `-l, --local` | Log in only for the current project. Default: `false`. | +| `-k, --api-key ` | API key for the NanoForge registry. | + +```bash +nf login --api-key +``` + +## logout + +Log out from the NanoForge registry. + +```bash +nf logout +``` + +| Option | Description | +| ----------------------------- | ------------------------------------- | +| `-d, --directory ` | Working directory of the command. | +| `-l, --local` | Log out only for the current project. | + +## publish + +Publish a package to the NanoForge registry. + +```bash +nf publish +``` + +| Option | Description | +| ----------------------------- | --------------------------------- | +| `-d, --directory ` | Working directory of the command. | + +## unpublish + +Unpublish a package from the NanoForge registry. + +```bash +nf unpublish +``` + +| Option | Description | +| ----------------------------- | --------------------------------- | +| `-d, --directory ` | Working directory of the command. | diff --git a/docs/docs/configuration/1-configuration-file.mdx b/docs/docs/configuration/1-configuration-file.mdx new file mode 100644 index 0000000..c965263 --- /dev/null +++ b/docs/docs/configuration/1-configuration-file.mdx @@ -0,0 +1,82 @@ +--- +title: Configuration file +description: The nanoforge.config.json file consumed by the CLI +--- + +import { Tooltip } from "mintlify/components"; + +## Overview + +Every NanoForge project has a `nanoforge.config.json` at its root. The CLI reads this file to know +how to build, generate, and start your game. Commands accept `-c, --config ` to point at a +different file, and most fields can be overridden per run with command flags. + +## Top-level fields + +| Field | Type | Default | Description | +| --------------- | -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | `string` | `nanoforge-app` | The name of the application. | +| `language` | `"ts" \| "js"` | `ts` | Language used in the project. | +| `initFunctions` | `boolean` | `true` | Whether init function lifecycle hooks are wired up. | +| `client` | `object` | — | Client configuration. See below. | +| `server` | `object` | — | Server configuration. See below. | + +## `client` + +| Field | Type | Default | Description | +| ----------------- | --------- | ---------------------------------- | -------------------------------------- | +| `enable` | `boolean` | `true` | Whether the client is enabled. | +| `port` | `string` | `3000` | Port the client listens on. | +| `outDir` | `string` | `.nanoforge/client` | Build output directory for the client. | +| `build.entry` | `string` | `client/main.ts` | Client entry file. | +| `build.staticDir` | `string` | `client/static` | Client static assets directory. | +| `editor.entry` | `string` | `.nanoforge/editor/client/main.ts` | Editor entry file for the client. | +| `editor.save` | `string` | `.nanoforge/client.save.json` | Editor save file for the client. | +| `dirs.components` | `string` | `client/components` | Where client components live. | +| `dirs.systems` | `string` | `client/systems` | Where client systems live. | + +## `server` + +The `server` block mirrors `client`, minus `port`. It is disabled by default. + +| Field | Type | Default | Description | +| ----------------- | --------- | ---------------------------------- | -------------------------------------- | +| `enable` | `boolean` | `false` | Whether the server is enabled. | +| `outDir` | `string` | `.nanoforge/server` | Build output directory for the server. | +| `build.entry` | `string` | `server/main.ts` | Server entry file. | +| `build.staticDir` | `string` | `server/static` | Server static assets directory. | +| `editor.entry` | `string` | `.nanoforge/editor/server/main.ts` | Editor entry file for the server. | +| `editor.save` | `string` | `.nanoforge/server.save.json` | Editor save file for the server. | +| `dirs.components` | `string` | `server/components` | Where server components live. | +| `dirs.systems` | `string` | `server/systems` | Where server systems live. | + +## Example + +```json +{ + "name": "my-game", + "language": "ts", + "initFunctions": true, + "client": { + "enable": true, + "port": "3000", + "outDir": ".nanoforge/client", + "build": { "entry": "client/main.ts", "staticDir": "client/static" }, + "editor": { + "entry": ".nanoforge/editor/client/main.ts", + "save": ".nanoforge/client.save.json" + }, + "dirs": { "components": "client/components", "systems": "client/systems" } + }, + "server": { + "enable": false, + "outDir": ".nanoforge/server", + "build": { "entry": "server/main.ts", "staticDir": "server/static" }, + "editor": { + "entry": ".nanoforge/editor/server/main.ts", + "save": ".nanoforge/server.save.json" + }, + "dirs": { "components": "server/components", "systems": "server/systems" } + } +} +``` diff --git a/docs/docs/configuration/2-environment-variables.mdx b/docs/docs/configuration/2-environment-variables.mdx new file mode 100644 index 0000000..74991af --- /dev/null +++ b/docs/docs/configuration/2-environment-variables.mdx @@ -0,0 +1,35 @@ +--- +title: Environment variables +description: Pass configuration to the client and server at runtime +--- + +import { Note } from "mintlify/components"; + +## Overview + +When running a NanoForge game (via `nf start`), environment variables can be passed to the client +and server through a `.env` file at the root of the project, or directly from the environment. + +```dotenv +NANOFORGE_CLIENT_SERVER_TCP_PORT=4445 +NANOFORGE_CLIENT_SERVER_UDP_PORT=4444 +NANOFORGE_CLIENT_SERVER_ADDRESS=127.0.0.1 +``` + +## Scoping by prefix + +Variables are scoped by their prefix, which controls where they are available: + +| Prefix | Availability | +| ------------------- | ----------------------------------- | +| `NANOFORGE_CLIENT_` | Available in the client only | +| `NANOFORGE_SERVER_` | Available in the server only | +| `NANOFORGE_` | Available in both client and server | + + + Prefixes are stripped before the variable is exposed to libraries. For example, + `NANOFORGE_CLIENT_SERVER_ADDRESS` is exposed to the client as `SERVER_ADDRESS`. + + +For full documentation on how libraries consume these variables, see +[`@nanoforge-dev/config`](https://github.com/NanoForge-dev/Engine/tree/main/packages/config). diff --git a/docs/docs/getting-started/1-introduction.mdx b/docs/docs/getting-started/1-introduction.mdx new file mode 100644 index 0000000..5dcce00 --- /dev/null +++ b/docs/docs/getting-started/1-introduction.mdx @@ -0,0 +1,43 @@ +--- +title: Introduction +description: What the NanoForge CLI is and what you can do with it +--- + +import { Card, CardGroup } from "mintlify/components"; + +## What is the NanoForge CLI? + +The NanoForge CLI (`nf`) is the main entry point for building, running, and deploying games made +with [NanoForge](https://github.com/NanoForge-dev) — a powerful game engine for the web browser. + +It wraps every step of the development lifecycle behind a single command: scaffolding a new project, +generating ECS components and systems, running your game in development mode, building for +production, and publishing reusable packages to the NanoForge registry. + +## What can it do? + + + + Create a fully configured project — client, optional server, linting, and Docker — in one + command. + + + Run your game locally with hot reloading, then start it as you would in production. + + + Generate components, systems, and entry files from your configuration. + + + Publish and consume components, systems, and libraries through the NanoForge registry. + + + +## Where to go next + +- New to NanoForge? Start with [Installation](./2-installation) then the + [Quickstart](./3-quickstart). +- Looking for a specific flag? See the [Commands reference](../commands/1-overview). +- Want a task-oriented walkthrough? Browse the [Guides](../../guides/cli/1-overview). + +See the [changelog](https://github.com/NanoForge-dev/CLI/blob/main/CHANGELOG.md) for the full +release history. diff --git a/docs/docs/getting-started/2-installation.mdx b/docs/docs/getting-started/2-installation.mdx new file mode 100644 index 0000000..1bdbbb8 --- /dev/null +++ b/docs/docs/getting-started/2-installation.mdx @@ -0,0 +1,40 @@ +--- +title: Installation +description: Install the NanoForge CLI and verify your setup +--- + +import { Tab, Tabs } from "mintlify/components"; + +## Requirements + +- **Node.js** 20 or later +- A package manager: `npm`, `yarn`, `pnpm`, or `bun` + +## Install globally + +Installing the CLI globally exposes the `nf` command everywhere on your machine. + + + ```bash npm install -g @nanoforge-dev/cli ``` + ```bash pnpm add -g @nanoforge-dev/cli ``` + ```bash yarn global add @nanoforge-dev/cli ``` + ```bash bun add -g @nanoforge-dev/cli ``` + + +## Verify the installation + +```bash +nf --version +nf --help +``` + +`nf --help` lists every available command. To see the options for a specific command, append +`--help` to it: + +```bash +nf new --help +``` + +## Next steps + +Continue to the [Quickstart](./3-quickstart) to create and run your first project. diff --git a/docs/docs/getting-started/3-quickstart.mdx b/docs/docs/getting-started/3-quickstart.mdx new file mode 100644 index 0000000..a6b52ac --- /dev/null +++ b/docs/docs/getting-started/3-quickstart.mdx @@ -0,0 +1,63 @@ +--- +title: Quickstart +description: Create, run, and build your first NanoForge project +--- + +import { Step, Steps } from "mintlify/components"; + +This quickstart takes you from an empty folder to a running game in a few minutes. + + + + Run the interactive scaffolder and answer the prompts (project name, language, package manager, + whether to include a server, and so on): + + ```bash + nf new + ``` + + Prefer a non-interactive run? Pass the answers as flags: + + ```bash + nf new --name my-game --language ts --package-manager pnpm --server + ``` + + + + + ```bash + cd my-game + ``` + + The scaffolder generates a `nanoforge.config.json` at the root. See + [Configuration](../configuration/1-configuration-file) for what every field means. + + + + + Start the game locally with file watching: + + ```bash + nf dev + ``` + + + + + ```bash + nf build + ``` + + Then start the built game: + + ```bash + nf start + ``` + + + + +## Where to go next + +- Learn each command in detail in the [Commands reference](../commands/1-overview). +- Follow task-oriented [Guides](../../guides/cli/1-overview) for common workflows. diff --git a/docs/docs/getting-started/index.mdx b/docs/docs/getting-started/index.mdx deleted file mode 100644 index 609b2a6..0000000 --- a/docs/docs/getting-started/index.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: CLI ---- - -# CLI - -The nanoforge CLI is the main tool to use when building or deploying a NanoForge application. - -To install the NanoForge CLI use: - -```bash -npm install -g @nanoforge-dev/cli -``` - -For usage information see [Usage](./usage.mdx). diff --git a/docs/docs/getting-started/usage.mdx b/docs/docs/getting-started/usage.mdx deleted file mode 100644 index 2e0b36f..0000000 --- a/docs/docs/getting-started/usage.mdx +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Usage ---- - -# Usage - -## Creating a new project - -In order to create a new project you need to run: - -```bash -nf new -``` - -## Commands - -Multiple commands exist in the CLI: - -- [build](#build) -- [create](#create) -- [dev](#dev) -- [editor](#editor) -- [generate](#generate) -- [install/add](#install/add) -- [login](#login) -- [logout](#logout) -- [new](#new) -- [publish](#publish) -- [start](#start) -- [unpublish](#unpublish) - -## build - -Used to build your nanoforge project. - -- `-d, --directory ` specify the working directory of the command. -- `-c, --config ` path to the config file. ([Schema](./config.schema.json)) -- `--client-entry ` specify the entry file of the client. -- `--server-entry ` specify the entry file of the server. -- `--client-static-dir ` specify the static directory of the client. -- `--server-static-dir ` specify the static directory of the server. -- `--client-out-dir ` specify the output directory of the client. -- `--server-out-dir ` specify the output directory of the server. -- `--editor` build with editor config. -- `--watch` build app in watching mode. (default: `false`) - -## create - -Used to create nanoforge components or systems. - -- `` the type to create (component or system). -- `-d, --directory ` specify the working directory of the command. -- `-c, --config ` path to the config file. ([Schema](./config.schema.json)) -- `-n, --name ` name of the component/system. -- `-s, --server` create on server instead of client. (default: `false`) -- `-p, --path ` path to the component/system folder. - -## dev - -Used to run your nanoforge project in dev mode. - -- `-d, --directory ` specify the working directory of the command. -- `-c, --config ` path to the config file. ([Schema](./config.schema.json)) -- `--generate` generate app files from config, like generate command in dev mode. (default: `false`) - -## editor - -Used to start the nanoforge editor. - -- `[path]` path to the project to open in the editor. -- `-d, --directory ` specify the working directory of the command. -- `--open` open the editor in the default web browser (default: `true` if path is specified, `false` otherwise). -- `--no-open` do not open the editor in the default web browser. - -## generate - -Used to generate nanoforge project files from config. - -- `-d, --directory ` specify the working directory of the command. -- `-c, --config ` path to the config file. ([Schema](./config.schema.json)) -- `--editor` generate the editor main file. -- `--watch` generate app in watching mode. (default: `false`) - -## install/add - -Used to add nanoforge components, systems or libraries to your project. - -- `[names...]` names of the components/systems/libraries to install. -- `-d, --directory ` specify the working directory of the command. -- `-l, --lib` install a library instead of a component/system. (default: `false`) -- `-s, --server` install on server instead of client. (default: `false`) - -## login - -Used to log in to the Nanoforge registry. - -- `-d, --directory ` specify the working directory of the command. -- `-l, --local` log in only for the current project. (default: `false`) -- `-k, --api-key ` API key for the Nanoforge registry. - -## logout - -Used to log out from the Nanoforge registry. - -- `-d, --directory ` specify the working directory of the command. -- `-l, --local` log out only for the current project. - -## new - -Used to create a new nanoforge project. - -- `-d, --directory ` specify the working directory of the command. -- `--name ` specify the name of your project. -- `--path ` specify the relative path where your project will be created (default: name of the project). -- `--package-manager ` specify the package manager of your project. -- `--language ` specify the language of your project. -- `--strict` use strict mode. -- `--no-strict` do not use strict mode. -- `--server` create a server. -- `--no-server` do not create a server. -- `--init-functions` initialize functions. -- `--no-init-functions` do not initialize functions. -- `--skip-install` skip installing dependencies. -- `--no-skip-install` do not skip installing dependencies. -- `--docker` generate docker files. -- `--no-docker` do not generate docker files. -- `--no-lint` do not generate lint files. -- `--editor` add editor dependencies. -- `--git` generate a git repository. -- `--no-git` do not generate a git repository. -- `--git-remote ` set up a git remote (required if `--git` is used). -- `--no-git-remote` do not set up a git remote. - -## publish - -Used to publish a package to the Nanoforge registry. - -- `-d, --directory ` specify the working directory of the command. - -## start - -Used to start your nanoforge project. - -- `-d, --directory ` specify the working directory of the command. -- `-c, --config ` path to the config file (default: "nanoforge.config.json"). ([Schema](./config.schema.json)) -- `-p, --port ` specify the port of the loader (the website to load the game). -- `--client-dir ` specify the directory of the client. -- `--server-dir ` specify the directory of the server. -- `--watch` run app in watching mode. (default: `false`) -- `--cert ` path to the SSL certificate for HTTPS. -- `--key ` path to the SSL key for HTTPS. - -## unpublish - -Used to unpublish a package from the Nanoforge registry. - -- `-d, --directory ` specify the working directory of the command. - -## Environment Variables - -When running a NanoForge game (via `nf start`), environment variables can be passed to the client and server applications through a `.env` file at the root of the project or directly in the environment. - -```dotenv -NANOFORGE_CLIENT_SERVER_TCP_PORT=4445 -NANOFORGE_CLIENT_SERVER_UDP_PORT=4444 -NANOFORGE_CLIENT_SERVER_ADDRESS=127.0.0.1 -``` - -Variables are scoped by prefix: - -| Prefix | Availability | -| ------------------- | ----------------------------------- | -| `NANOFORGE_CLIENT_` | Available in the client only | -| `NANOFORGE_SERVER_` | Available in the server only | -| `NANOFORGE_` | Available in both client and server | - -> **Note:** Prefixes are stripped before the variable is exposed to libraries. - -For full documentation on how libraries consume these variables, see `@nanoforge-dev/config `\_\_. diff --git a/docs/guides/cli/1-overview.mdx b/docs/guides/cli/1-overview.mdx new file mode 100644 index 0000000..eec3f3a --- /dev/null +++ b/docs/guides/cli/1-overview.mdx @@ -0,0 +1,28 @@ +--- +title: Guides +description: Task-oriented walkthroughs for common NanoForge CLI workflows +--- + +import { Card, CardGroup } from "mintlify/components"; + +The [Commands reference](../../docs/commands/1-overview) documents what each command does. These guides +take the opposite angle: they follow the **paths a user actually walks** when building a game with +the CLI, stitching commands together end to end. + + + + Scaffold a project, understand what was generated, and run it. + + + Use dev mode and regenerate files as you change your configuration. + + + Produce a production build and serve it, optionally over HTTPS. + + + Create your own ECS pieces or install shared ones from the registry. + + + Authenticate and share a component, system, or library with others. + + diff --git a/docs/guides/cli/2-create-a-project.mdx b/docs/guides/cli/2-create-a-project.mdx new file mode 100644 index 0000000..6d7290b --- /dev/null +++ b/docs/guides/cli/2-create-a-project.mdx @@ -0,0 +1,51 @@ +--- +title: Create your first project +description: Scaffold a NanoForge project and understand the result +--- + +import { Step, Steps } from "mintlify/components"; + +This guide walks the most common starting point: turning an idea into a runnable project. + + + + The interactive scaffolder is the easiest way to start: + + ```bash + nf new + ``` + + You'll be asked for a name, language, package manager, and whether to include a server, Docker + files, git, and so on. To skip the prompts, pass the answers as flags: + + ```bash + nf new --name my-game --language ts --package-manager pnpm --server + ``` + + See [`nf new`](../../docs/commands/2-commands/1-new) for the full flag list. + + + + + Move into the project and inspect it: + + ```bash + cd my-game + ``` + + The most important file is `nanoforge.config.json`, the central configuration the CLI reads for + every command. Each field is documented in + [Configuration file](../../docs/configuration/1-configuration-file). + + + + + ```bash + nf dev + ``` + + Your game now runs locally in development mode. The next guide, + [Develop locally](./3-develop-locally), goes deeper into the dev workflow. + + + diff --git a/docs/guides/cli/3-develop-locally.mdx b/docs/guides/cli/3-develop-locally.mdx new file mode 100644 index 0000000..2358fe5 --- /dev/null +++ b/docs/guides/cli/3-develop-locally.mdx @@ -0,0 +1,50 @@ +--- +title: Develop locally +description: Iterate on your game with dev mode and file generation +--- + +import { Note, Step, Steps } from "mintlify/components"; + +Once a project exists, most of your time is spent in the develop-and-iterate loop. + + + + ```bash + nf dev + ``` + + `nf dev` serves the game and watches your files, so changes are picked up as you work. Keep it + running in a dedicated terminal. + + + + + When you change `nanoforge.config.json` — for example adding new component or system directories + — regenerate the project files. You can do this in a one-off run: + + ```bash + nf generate + ``` + + Or have dev mode regenerate as it runs: + + ```bash + nf dev --generate + ``` + + + + + Working in a monorepo or with multiple configs? Every command accepts `-d` and `-c`: + + ```bash + nf dev -d ./packages/game -c nanoforge.dev.json + ``` + + + + + + Need runtime values like a server address or ports? Put them in a `.env` file — see [Environment + variables](../../docs/configuration/2-environment-variables). + diff --git a/docs/guides/cli/4-build-and-deploy.mdx b/docs/guides/cli/4-build-and-deploy.mdx new file mode 100644 index 0000000..f833bc0 --- /dev/null +++ b/docs/guides/cli/4-build-and-deploy.mdx @@ -0,0 +1,54 @@ +--- +title: Build & deploy +description: Produce a production build and serve it +--- + +import { Note, Step, Steps } from "mintlify/components"; + +When your game is ready to ship, the build-and-serve path takes it from source to a running +production instance. + + + + ```bash + nf build + ``` + + The client and server are compiled into the output directories defined in your + [configuration](../../docs/configuration/1-configuration-file) (`.nanoforge/client` and + `.nanoforge/server` by default). Override any path per run, for example: + + ```bash + nf build --client-out-dir dist/client --server-out-dir dist/server + ``` + + + + + ```bash + nf start + ``` + + `nf start` launches the loader (the website that loads the game) and the server when enabled. + Choose the loader port with `-p`: + + ```bash + nf start --port 8080 + ``` + + + + + Provide a certificate and key to serve securely: + + ```bash + nf start --cert ./certs/cert.pem --key ./certs/key.pem + ``` + + + + + + Scaffolding with `nf new --docker` generates Docker files so you can containerize the build for + deployment. + diff --git a/docs/guides/cli/5-components-and-systems.mdx b/docs/guides/cli/5-components-and-systems.mdx new file mode 100644 index 0000000..74e0964 --- /dev/null +++ b/docs/guides/cli/5-components-and-systems.mdx @@ -0,0 +1,52 @@ +--- +title: Add components & systems +description: Create your own ECS pieces or install shared ones +--- + +import { Step, Steps } from "mintlify/components"; + +NanoForge games are built from ECS **components** and **systems**. You can author your own or pull +ready-made ones from the registry. + +## Create your own + + + + ```bash + nf create component --name Position + ``` + + Files are created under the client's component directory by default. Target the server with + `--server`. + + + + + ```bash + nf create system --name Movement --server + ``` + + See [`nf create`](../../docs/commands/2-commands/6-create) for all options. + + + + +## Install shared ones + +To reuse components, systems, or libraries published to the NanoForge registry: + +```bash +# a component or system +nf install my-org/health-bar + +# a library, on the server +nf add my-org/physics --lib --server +``` + +If the package lives in a private scope, [log in](../../docs/commands/2-commands/9-registry) first: + +```bash +nf login --api-key +``` + +See [`nf install`](../../docs/commands/2-commands/7-install) for the full reference. diff --git a/docs/guides/cli/6-publish-a-package.mdx b/docs/guides/cli/6-publish-a-package.mdx new file mode 100644 index 0000000..c5ebe01 --- /dev/null +++ b/docs/guides/cli/6-publish-a-package.mdx @@ -0,0 +1,43 @@ +--- +title: Publish a package +description: Share a component, system, or library through the registry +--- + +import { Note, Step, Steps } from "mintlify/components"; + +Once you've built something reusable, you can publish it to the NanoForge registry so other projects +can `nf install` it. + + + + Log in with your API key. Authentication is global by default; use `-l` to scope it to the + current project only: + + ```bash + nf login --api-key + ``` + + + + + From the package directory: + + ```bash + nf publish + ``` + + + +```bash nf unpublish ``` + + + ```bash + nf logout + ``` + + + + + All four commands are documented together under [registry + commands](../../docs/commands/2-commands/9-registry). +