Popcorn Web

Popcorn Web is a small, TinyGo-oriented web application framework for Go, built directly on net/http. Templates, SQL, request binding, and OpenAPI compile to typed Go ahead of time, so a renamed template argument or a SELECT that no longer matches its result type is a build error rather than a production incident. Nothing is rediscovered by reflection at request time, which is also what lets the same source compile under TinyGo.

Routing is net/http's own ServeMux, handlers stay http.HandlerFunc, and queries return through database/sql — so the middleware, httptest tests, and http.Handlers already in your codebase keep working, and a handler can leave this framework as easily as it entered.

Documentation: https://shibukawa.github.io/popcornweb/

Quick start

brew install shibukawa/tap/pw
pw init myapp
cd myapp
pw dev

pw init asks about ten choices and then writes a project that already compiles: a handler, a typed page, a document shell, error pages, configuration, and a devbox.json. It runs go mod tidy and pw generate before reporting success, so there is no separate setup step afterwards. pw dev then starts the declared services, regenerates code, applies pending migrations, builds, runs, and restarts on every change — Ctrl-C stops all of it together.

Generated projects pin their own Go toolchain, so you do not need a matching Go installed before creating one. Devbox is optional; if Go is on PATH, run pw dev directly.

Installing

The pw command

pw handles scaffolding, code generation, formatting, migrations, and the development server. Install it first.

Channel	Command	Covers
Homebrew	brew install shibukawa/tap/pw	macOS (Apple Silicon and Intel), Linux
Nix	nix run github:shibukawa/popcornweb#pw -- version	x86_64-linux, aarch64-linux, aarch64-darwin
Release archive	releases page	every target, and the only channel covering Windows
Go toolchain	go install github.com/shibukawa/popcornweb/cmd/pw@latest	anywhere a matching Go toolchain is installed

Homebrew and the release archives ship a prebuilt binary; the Nix derivation and go install build from source. go install is listed last because it needs a Go toolchain matching the module's requirement, which is exactly the prerequisite the other three channels remove. The flake also exposes a devShells.default with Go, gopls, and TinyGo if you want the host toolchain without Devbox.

Confirm the installation with pw version.

The library

Popcorn Web requires Go 1.27 or later. pw init writes a go.mod that already requires the framework; an existing module needs one step:

go get github.com/shibukawa/popcornweb

Application code imports pw, which is the stable application-facing API:

import "github.com/shibukawa/popcornweb/pw"

Using pw

One command covers the project lifecycle. Every command except pw init finds the project by walking upward from the working directory until it reaches popcornweb.toml, so all of them work from any nested directory.

Command	Purpose
pw init	create a runnable project in a new directory
pw add	enable a capability the project declined at init
pw new	scaffold one more handler or page
pw generate	write everything a compiler needs, stopping before the compiler
pw check	report generated files that are stale or missing
pw fmt	format template sources into their canonical form
pw i18n	reconcile message catalogs against the templates that use them
pw migrate	inspect, apply, and roll back migrations
pw seed	load seed datasets
pw build	generate and compile a release binary
pw dev	watch, regenerate, migrate, rebuild, and restart

pw build --backend selects the HTTP implementation (nethttp or fasthttp) and --target selects deployment packaging (lambda, azure-functions, google-cloud-run-functions, vercel-go). Run pw help for the full flag list of every command.

What the code looks like

A .pw.html file is a typed template language that compiles to Go. Its parameters become a Go struct, so misspelling one is a generation error with a position rather than a blank region at runtime.

package handlers

export component Home(count: int): html {
  <main>
    <h1>Hello, World!</h1>
    <p>Page views: <strong>{count}</strong></p>
  </main>
}

A .pw.sql file is the same idea for queries. The result contract is declared, and a projection that stops matching it fails generation.

package queries

type AccessCounter { count: int }

export statement IncrementAccess(): sql.one<AccessCounter> {
  INSERT INTO access_counter (id, count)
  VALUES (1, 1)
  ON CONFLICT(id) DO UPDATE SET count = access_counter.count + 1
  RETURNING count
}

The handler that joins them is a plain http.HandlerFunc:

package handlers

import (
	"net/http"

	"github.com/shibukawa/popcornweb/pw"
	"myapp/queries"
)

func init() { mux.HandleFunc("GET /{$}", home) }

func home(w http.ResponseWriter, r *http.Request) {
	counter, err := queries.IncrementAccess(r.Context())
	if err != nil {
		pw.WriteProblem(w, r, pw.InternalServerError(err))
		return
	}
	pw.WriteHTML(w, r, Home(HomeParams{Count: counter.Count}))
}

pw generate writes the _pw_gen.go files that back Home, HomeParams, and queries.IncrementAccess. They are build output, excluded by the .gitignore pw init wrote, and never edited by hand.

Features

Core

Feature
Standard-library routing	pw.ServeMux is a type alias for net/http.ServeMux — same patterns, wildcards, and precedence
Registered and discovered routing	register routes explicitly, or let a directory tree declare them
Middleware	ordinary func(http.Handler) http.Handler, plus request IDs, recovery, body limits, and request-scoped loggers
Typed configuration	TOML and environment variables, per-environment, with scaffolds generated from the declarations
Custom commands	typed CLI subcommands on the deployed binary
Operational endpoints	health, readiness, OpenAPI, graceful shutdown, reverse-order cleanup

Frontend and rendering

Feature
Typed templates	.pw.html components with typed parameters, compiled to Go
Scoped styles and Tailwind	a component's <style> block is namespaced at compile time; Tailwind is one pw add tailwind away
Responses	HTML, JSON, XML, CSV, redirects, downloads, and RFC 9457 problem documents
Async rendering	stream the page around a boundary that is still loading
Live rendering	keep updating a region while the reader stays on the page
Partial updates	answer a same-origin link with only the regions whose markup differs
Rendering cache	cache rendered output by scope
Static assets	embedded, fingerprinted asset serving
i18n	message catalogs reconciled against the templates that use them, plus locale routing

Interactivity

Feature
Server actions	name a Go function from a template instead of writing its URL
Forms	client-side feedback that agrees with the server-side checks, and suggestion lists that need no script
Fragments	server-rendered fragments combined with dialogs, popovers, and custom elements
Navigation	view transitions and speculation rules, so ordinary page-to-page navigation feels continuous
Signals	a named instruction from a live source to code the page registered
Component scripts and browser controls	the small amount of browser code a server-rendered page still needs
htmx and React	supported when you want them, not required
Typed streams	one response as a sequence of typed events — SSE, NDJSON, or a JSON array, chosen by the client
WebSocket

Storage

Feature
Typed SQL	.pw.sql compiled to typed Go over database/sql
Relational databases	SQLite, PostgreSQL, and MySQL/MariaDB, each on TinyGo as well
DynamoDB and Firestore	typed .pw.dynamo and Firestore templates
Object storage	uploads in S3-compatible storage, through a TinyGo-capable S3 client
Batching	cutting the cost of many statements — a transaction on SQLite, Batch and COPY on PostgreSQL
Data cache	reuse what an upstream call returned for the same typed question, with concurrent misses collapsed onto one call
Migrations and seed data	applied by pw migrate and pw dev

Authentication and security

Feature
What is defended by default	what the framework handles, what it hands you, and where a request is checked before your handler runs
Authentication	OpenID Connect (Authorization Code with PKCE), WebAuthn passkeys, or both; jwt_only verifies a bearer token without mounting a login
Sessions	opaque server-side sessions or sealed cookies, over several stores
Security headers	validated browser policy by default, plus CSRF
CORS and rate limiting	configuration switches rather than assembled stacks

Operations

Feature
OpenTelemetry	structured logs and traces, with framework spans reaching each SQL statement
OpenAPI 3.1	generated from the handlers, bindings, and comments already in the code
Compression	negotiated zstd and gzip, off by default because a proxy usually owns it
pw doctor	resolves a named environment and reports missing, conflicting, or unsafe settings before deployment
Dev console	routes, queries, storybook, telemetry, and diagnostics during pw dev
Testing	run an application from an isolated copy of every registered configuration, with E2E support

Build and deployment targets

Target
Go and TinyGo	the same source, with no reflection in the generated path
net/http and fasthttp	selected by pw build --backend
Containers	image builds from the project
Serverless	AWS Lambda, Azure Functions, Google Cloud Run functions, Vercel
Reverse proxy and service proxy	in front of, or from within, the application

Examples

examples/ holds complete applications, each with its own README.

Example
helloworld	the pw init scaffold, with a SQLite counter
todo	one todo list written twice against one PostgreSQL table — once with net/http and pgx, once with the framework — so binary size and throughput are measured on identical behaviour
async_render	a page whose slow sections stream in afterwards
live_render	two regions that keep changing on the server's clock
partial_update	two routes under one layout, with a table whose rows update in place
htmx_fragment	a task board where every interaction re-renders one region
websocket_chat	a chat room over a typed WebSocket, in both builds
oidclogin	browser login through OpenID Connect
passkeylogin	OpenID Connect creates the account, a passkey handles repeat login

Editor support

tools/vscode is a Visual Studio Code extension that highlights the three source dialects — .pw.html, .pw.sql, and .pw.dynamo — including the template expressions embedded in their HTML, SQL, and clause bodies. It is a grammar only: nothing is executed, no binary is needed, and it works on a file opened with no workspace. Diagnostics and completion are planned for a later version through a pw lsp language server.

Documentation

• Why Popcorn Web — what the project is trying to do, and the measurements behind it
• Installation
• Tutorial — five chapters from an empty directory to a login
• Guides — one page per feature, in English and Japanese
• Performance — binary size and throughput per build target, and what changes when you switch
• Reference — the runtime API, the template and query languages, and every configuration key

License

Apache License 2.0. See LICENSE.

The MySQL driver carried by tinygodriver includes an MPL-2.0 TinyGo fork; that notice travels with any artifact that links it.