Frontend

The frontend presents user-facing web pages on pkg.go.dev.

For additional information on functionality of the frontend, see the design document.

Development

The main program lives in cmd/frontend. The bulk of the code lives in internal/frontend.

See experiment.md for instructions how to enable experiments.

Running

You can run the frontend locally like so:

go run ./cmd/frontend [-dev] [-direct_proxy]

The -dev flag reloads templates on each page load and rebuilds JavaScript assets when TypeScript source files change.

The frontend can use one of two datasources:

Postgres database
Proxy service

The Datasource interface implementation is available at internal/datasource.go.

You can use the -direct_proxy flag to run the frontend with its datasource as the proxy service. This allows you to run the frontend without setting up a postgres database.

Alternatively, you can run pkg.go.dev with a local database. See instructions on how to set up and populate your local database with packages of your choice.

You can then run the frontend with: go run ./cmd/frontend

If you add, change or remove any inline scripts in templates, run devtools/cmd/csphash to update the hashes. Running all.bash will do that as well.

Local mode

You can also use run the frontend locally with an in-memory datasource populated with modules loaded from your local filesystem.

go run ./cmd/pkgsite [path1,path2]

This allows you to run the frontend without setting up a database and to view documentation of local modules without requiring a proxy. The command accepts a list of comma-separated strings each representing a path of a module to load into memory.

Screentest

In addition to tests written in Go inside internal/frontend and internal/testing/integration, pages on pkg.go.dev may have image snapshot tests. These tests will create diffs for inspection on failure.

These tests are in the tests/screentest/ directory. For details, see tests/README.md.

Static Assets

JavaScript assets for pkg.go.dev are compiled from TypeScript files in the content/static/js directory. The compiled assets are committed to the repo so the frontend or worker service can be run without any additional steps from a new clone of the project.

Building

When modifying any TypeScript code, you must run go run ./devtools/cmd/static before committing your changes.

NPM Dependency Management

This project is architected to be free from a Node.js runtime dependency in production. Node.js and npm are used exclusively for development tasks such as linting, unit testing, and type checking.

Production Bundles: The Go-based esbuild orchestrator (located in internal/static/static.go) bundles TypeScript and CSS into minified assets. These bundles are designed to be "dependency-free" and rely solely on standard Web APIs and local modules. The generated bundles are located in the static/ directory.
Third-party Libraries: External libraries listed in package.json are used only for testing environments (markdown for static/markdown.ts, jest, js-green-licenses, eslint, ...) and must not be included in the production JavaScript served by the frontend.