Installing & Running nojs¶

⚠️ Status: nojs is an experimental MVP. The API may change before a stable release.

Prerequisites¶

Go 1.25+ — https://go.dev/dl/
Make — pre-installed on Linux/macOS; on Windows use WSL
A static file server — python3 -m http.server works fine, or any alternative

Step 1 — Clone the repository¶

git clone https://github.com/ForgeLogic/nojs.git
cd nojs

Step 2 — Copy the demo app as your starting point¶

The app/ directory is a fully wired-up example application. It contains everything you need: the HTML shell, the WASM bootstrap files, a working Makefile, and example components. Copy it to a new location to use as your project scaffold:

cp -r app/ ~/projects/my-nojs-app
cd ~/projects/my-nojs-app

The copied directory has this structure:

my-nojs-app/
├── go.mod                          ← rename the module here
├── go.sum
├── internal/
│   └── app/
│       ├── main.go                 ← WASM entrypoint
│       ├── routes.go               ← route registration
│       └── components/             ← your components go here
│           └── pages/
│               └── ...
└── wwwroot/
    ├── index.html                  ← HTML shell (no changes needed)
    ├── core.js                     ← framework bootstrap (no changes needed)
    ├── wasm_exec.js                ← ⚠️ must be refreshed (see Step 3)
    └── main.wasm                   ← generated by `make wasm`

Step 3 — Copy `wasm_exec.js`¶

wasm_exec.js is the Go WASM runtime bridge and must match your local Go version. It is not included in the repository and must be copied from your local Go installation:

cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" ./app/wwwroot/

⚠️ Repeat this step any time you upgrade Go. A mismatched wasm_exec.js will silently fail to load the WASM module.

Step 4 — Rename the module¶

Open go.mod and change the module path to match your project:

module github.com/YourOrg/your-app

Update any internal imports that reference github.com/ForgeLogic/app to use the new module path.

Step 5 — Point at the framework modules¶

While nojs is in active development the modules are referenced via replace directives. Update go.mod to point at your local clone of the framework:

replace github.com/ForgeLogic/nojs => /path/to/nojs/nojs
replace github.com/ForgeLogic/nojs-router => /path/to/nojs/router

Note: Once nojs is published to pkg.go.dev, you will be able to use go get github.com/ForgeLogic/nojs@latest and remove the replace directives.

Step 6 — Build and run¶

# Compile templates + build WASM
make full

# Start the dev server (default: port 9090)
make serve

Open http://localhost:9090 in your browser. The console should print WebAssembly module loaded.

Tip: Enable "Disable cache" in DevTools → Network to ensure the WASM binary reloads on every refresh.

Build command reference¶

Command	Description
`make full`	Compile templates + build WASM (development)
`make full-prod`	Compile templates + build WASM (production/optimised)
`make wasm`	Rebuild WASM only — fast refresh, skips templates
`make serve`	Start dev server on port 9090
`make clean`	Remove generated `main.wasm`
`make lint-install`	Install golangci-lint v2.10.1 to `$GOPATH/bin`
`make lint`	Run golangci-lint on compiler and nojs modules
`make docs-install`	Install MkDocs dependencies to `.venv-docs`
`make docs-build`	Build static documentation site to `site/` directory
`make docs-serve`	Run local MkDocs server (typically http://localhost:8000)

When to use make wasm vs make full:
Use make wasm when you only changed .go files. Use make full when you created or modified any .gt.html template — templates must be recompiled before the WASM binary is built.

Troubleshooting¶

Symptom	Fix
`WebAssembly module loaded` not in console	Check that `wasm_exec.js` and `core.js` are in `wwwroot/` and included in `index.html`
Stale output after code changes	Rebuild with `make wasm` (or `make full` for template changes), then hard-refresh
`wasm_exec.js` errors after Go upgrade	Re-copy from `$(go env GOROOT)/misc/wasm/wasm_exec.js`
Exported Go function is `undefined` in JS	Ensure `main.go` registered it with `js.Global().Set(...)` and WASM was rebuilt
Template changes not reflected	Run `make full` — templates must be recompiled before `make wasm`

Installing and running the linter¶

The nojs framework uses golangci-lint to enforce code quality across its modules.

Install the linter¶

make lint-install

This installs golangci-lint v2.10.1 to your Go bin directory ($GOPATH/bin).

Note: You only need to run this once. The linter is persisted in your Go environment.

Run the linter¶

make lint

This runs golangci-lint against the compiler and nojs modules. The linter checks for: - Code style violations - Potential bugs and inefficiencies - Naming conventions - Unused variables and imports

Linter configuration¶

golangci-lint reads its configuration from .golangci.yml in the module root (if present). Each module may have its own linter settings.

Installing and running the documentation server¶

The nojs documentation is built with MkDocs and can be served locally for development and review.

Install documentation dependencies¶

make docs-install

This creates a Python virtual environment (.venv-docs) and installs the dependencies listed in requirements-docs.txt. This only needs to be done once.

Prerequisites: Python 3.8+ must be installed on your system.

Run the documentation server¶

make docs-serve

This starts a local MkDocs development server, typically on http://localhost:8000. The server watches for changes and automatically rebuilds the documentation as you edit markdown files.

Tip: Open your browser to the displayed URL (usually http://localhost:8000) to view the docs. The page will auto-refresh on edits.

Build the documentation site¶

If you want to generate a static HTML site without serving it:

make docs-build

This builds the documentation to the site/ directory with strict mode enabled (fails on errors).

Next steps¶

Read the Quick Guide for a practical reference of all framework features
Browse the example components in app/internal/app/components/ to see working patterns
Read the NoJS Manifesto for the design philosophy behind the framework

Future: A nojs-starter template repository is planned to replace the manual copy step above.