Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Bundle JavaScript and CSS with Vite

Bundle JavaScript and CSS with Vite

Since v0.6.0

Add a frontend that Vite builds: TypeScript or JavaScript modules, CSS, and npm packages. Its pages update as you edit them in development, and its build is embedded in the app’s binary for production.

The templ pages and htmx of a web project need no build step. Use Vite when you want more: a charting library from npm, TypeScript, an interactive widget in one of your pages.

Before you start

  • A web project (Create a project). An API project’s frontend is a single-page app: see Build a single-page app.
  • Node.js 20.19 or later in 20, or 22.12 or later, with npm. Only the frontend needs it: the Go app doesn’t, and neither do its tests.

Steps

1. Add the frontend

In a new project:

anetos new shop --vite          # TypeScript; --vite=js for JavaScript

In an existing web project:

go tool anetos vite:install     # --js for JavaScript
go tool anetos agent:update     # so coding agents know about frontend/

Both write frontend/:

FileHolds
frontend/package.jsonThe packages (Vite; TypeScript with --vite) and the scripts: dev runs Vite, build type-checks and runs vite build
frontend/vite.config.tsWhere the build goes (../public/build, served under /build/), the manifest’s name, the entries (src/main.ts), and the names of the built files (below)
frontend/src/main.tsThe entry the layout loads; it imports main.css
frontend/tsconfig.jsonTypeScript’s settings (TypeScript only)
frontend/go.modA module of its own, which keeps go build ./... and go vet ./... out of node_modules, where some npm packages ship Go files

Then they connect the app to it:

  • In main.go’s setup, vite.New(app, public.Files), before web.NewServer.
  • In routes/web.go, the build’s route: r.Get("/build/{path...}", web.WrapHandler(vite.Handler())).
  • In views/layout.templ’s <head>, after @ui.Head(): @vite.Tags("src/main.ts"), and they run templ generate.
  • In .gitignore and .dockerignore, frontend/node_modules/ and public/build/.
  • In the Dockerfile, a Node stage (step 5).

They install the packages with npm (--skip-install skips it). If you changed one of those files so that vite:install can’t find its place in it, it leaves the file alone and prints what to add. It leaves the layout alone too when it couldn’t change main.go: the tags need vite.New.

2. Run it

go tool anetos dev

anetos dev starts Vite beside the app, on 127.0.0.1 and a port of its own (flags that win over vite.config’s server settings), and forwards /build/ to it, the hot reload’s WebSocket included. The browser sees one address, http://localhost:8080. It also sets VITE_DEV_URL=/build/ for the app, so @vite.Tags loads the sources from Vite:

<script type="module" src="/build/@vite/client"></script>
<script type="module" src="/build/src/main.ts"></script>

Edit frontend/src/main.css and the page changes without reloading. Edit a module and Vite updates it, or reloads the page when it can’t. Changes to Go and templ files rebuild the app, as before.

3. Write the frontend

Import modules and stylesheets from the entry:

// illustrative: frontend/src/main.ts
import './main.css'
import { formatPrice } from './prices'

document.querySelectorAll<HTMLElement>('[data-price]').forEach((el) => {
  el.textContent = formatPrice(Number(el.dataset.price))
})

Add packages in frontend/:

cd frontend && npm install chart.js

Styles in main.css load after the CSS framework’s stylesheet (public/static/app.css), so they win where both set a property. Files that need no build, such as a favicon, stay in public/static, served under /assets/.

4. Add entries

A page that needs its own script gets its own entry. List it in vite.config.ts’s inputs:

input: ['src/main.ts', 'src/charts.ts'],

and load it where it’s needed, in a templ page:

// illustrative
templ Dashboard(stats []Stat) {
	@vite.Tags("src/charts.ts")
	…
}

Each @vite.Tags call on a page, such as the layout’s and this one, writes the tags of its own entries, so what two entries share comes twice, and a stylesheet linked twice applies again where it’s linked the second time. Load an entry on its own, as above, when it imports nothing the layout’s entry imports. Otherwise load both with one call: @vite.Tags takes several entries, so the layout can take the page’s entries as a parameter.

For a file the build hashes, such as an image the frontend imports, vite.URL(ctx, "src/logo.svg") gives its URL.

5. Build for production

go tool anetos build

anetos build installs the packages if they need it, runs the frontend’s build script (TypeScript’s checks, then vite build into public/build), and builds the binary, which embeds public/build. The server needs neither Node nor frontend/.

The Dockerfile builds the frontend in a Node stage, with npm:

FROM node:22-alpine AS frontend
WORKDIR /src/frontend
COPY frontend/package.json frontend/package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY frontend/ ./
RUN npm run build

The Go stage copies public/build from it after COPY . . and runs go tool anetos build --no-frontend, since the frontend is built already. The stage needs frontend/package-lock.json, which installing the packages writes: commit it. With pnpm, yarn or bun, copy that manager’s lockfile instead, and install and build with it.

Complete example

anetos new shop --vite writes the files of step 1. The guide’s test makes such a project, builds it with Vite, and checks that the app embeds every file of the build.

How it works

vite build writes the files with a hash of their content in their names (assets/main-B7PI925R.js), and a manifest, public/build/manifest.json, saying which files each entry needs. The manifest gets that name because Vite’s default, .vite/manifest.json, is in a dot folder, which //go:embed leaves out. For the same reason, vite.config names the built files without a leading _ or . (src/_chart.ts builds into assets/chart-….js). Files of frontend/public, which Vite copies as they are, keep their names: don’t start them with _ or ..

vite.New reads the manifest when the app starts. For an entry, @vite.Tags writes:

  1. a stylesheet link for each of its CSS files and those of the chunks it imports;
  2. the entry’s <script type="module">, or its stylesheet link for a CSS entry;
  3. a modulepreload link for each chunk it imports.

vite.Handler serves the files under /build/. Those under assets/, whose names change with their content, may be cached for a year. Text files of 1 KiB or more are sent gzipped to clients that accept it. The manifest itself isn’t served.

Warning: where the app is deployed (APP_ENV=production or staging), vite.New refuses VITE_DEV_URL, which would make the pages load their scripts from a development server. It also refuses to start without the manifest, which means the frontend wasn’t built. Elsewhere, without a manifest, @vite.Tags writes an HTML comment saying so, and go run . doctor warns in development. A manifest that isn’t valid JSON stops the app everywhere.

The concept page on the frontend places Vite among the other ways to write pages.

Testing it

The app’s tests need no build: without a manifest, the tags are a comment, and the pages render. To test the frontend itself, use the JavaScript tools you know (Vitest, Playwright) in frontend/.

go tool anetos check runs the frontend’s build as a step of its own, before the Go build, so a type error in frontend/src fails it.

Common problems

SymptomCauseFix
anetos dev: the frontend (frontend/) needs Node.js 20.19 or 22.12 or laterNode.js isn’t installed, or is olderInstall Node.js from nodejs.org
The app doesn’t start in production: vite: read build/manifest.jsonThe binary was built without the frontend’s buildBuild with go tool anetos build, not go build, or run npm run build in frontend/ first
vite: VITE_DEV_URL is set with APP_ENV=productionA development setting reached the serverRemove VITE_DEV_URL from its environment
The page has <!-- vite: no build/manifest.json --> and no scriptsThe app runs without anetos dev and without a buildUse go tool anetos dev, or run npm run build in frontend/
vite: "src/charts.ts" isn't an entry of build/manifest.jsonThe entry isn’t in vite.config.ts’s inputs, or the build is olderAdd it to the inputs, and build again
anetos dev: the frontend's Vite stopped before it served (exit status 1); its output is aboveVite failed to start: an error in vite.config, or a plugin missing from node_modulesRead Vite’s message above it
A file under /build/ that the manifest names answers 404 from the binary, not in developmentIts name starts with _ or ., which //go:embed leaves out: a file of frontend/public, or vite.config lost its output namesRename the file, or restore the names from a new project’s vite.config
go vet ./... reports packages under frontend/node_modulesfrontend/go.mod was removedRestore it

Next steps