Doors Starter
A starter project for Doors — a reactive Go web framework built on GoX.
Project Structure
.
├── main.go # Entry point: creates the Doors app, attaches middleware, starts HTTP server
├── app.gox # Root component: HTML shell with head elements, nav, top-level doors.Route, and footer
├── go.mod / go.sum # Go module definition and dependency checksums
│
├── path/ # URL path models — Go structs describing URL shapes
│ └── root.go # Root path model: "/" and "/about" variants
│
├── components/ # Reusable UI components shared across pages
│ ├── nav.gox # Top navigation bar with doors.ALink navigation links
│ ├── footer.gox # Page footer
│ └── not_found.gox # 404 fallback page (a RouteBind leaf showing the unmatched path)
│
├── segments/ # Self-contained page groups (one per path model)
│ └── root/ # Segment for the "/" section
│ ├── main.gox # Routes(): the segment's route group (Root path model -> Landing or About)
│ ├── landing.gox # Landing page ("/") — includes the counter demo
│ ├── about.gox # About page ("/about")
│ └── counter.gox # Interactive counter (Source + Bind demo)
│
└── assets/ # Embedded static files
├── embed.go # Go embed directives exposing Style bytes and Static FS
├── style.css # Application stylesheet
└── static/ # Raw static files served via UseFS middleware
└── ico.png # Favicon
Generated .x.go files are auto-managed by GoX and omitted from this tree.
The segments/ layout above is a suggested convention, not a strict rule.
For larger sections you may want to split further — e.g. separate Go packages per page, or shared components/ and drivers/ packages within a segment. Keep the codebase systematically organized in whatever way fits your project.
How to Extend
Add a New Page to an Existing Path Model
If you want a new page under the existing Root path model (e.g. /contact):
-
Add the variant to path/root.go:
const (
RootLanding RootPage = iota
RootAbout
RootContact // new
)
Update the struct tag: `/:" | about | contact"`
-
Create a new page component in segments/root/:
elem Contact(p doors.Source[path.Root]) {
<title>Contact</title>
<h1>Contact</h1>
}
-
Add a new route to the RouteModel[path.Root] group in segments/root/main.gox:
doors.RouteMatch(
func(p path.Root) bool {
return p.Page == path.RootContact
},
doors.RouteSource(Contact),
),
RouteMatch takes a predicate and the routes to use when it holds; here a single RouteSource leaf, which hands Contact the writable doors.Source[path.Root].
-
Link to it in components/nav.gox:
<li>~topNavLink{model: path.Root{Page: path.RootContact}, text: "Contact"}</li>
Add a New Path Model (New Section)
To add an entirely new section like /blog, /blog/:id:
-
Create path/blog.go:
package path
type Blog struct {
Section BlogSection `/blog:" | :ID"`
ID string
}
type BlogSection int
const (
BlogIndex BlogSection = iota
BlogPost
)
-
Create segments/blog/main.gox with the segment's route group:
package blog
import (
"github.com/doors-dev/doors"
"github.com/doors-dev/doors-starter/path"
)
func Routes() doors.SourceRoute[doors.Location] {
return doors.RouteModel[path.Blog](
doors.RouteMatch(
func(p path.Blog) bool {
return p.Section == path.BlogIndex
},
doors.RouteSource(Index),
),
doors.RouteMatch(
func(p path.Blog) bool {
return p.Section == path.BlogPost
},
doors.RouteBeamDerive(
func(b doors.Beam[path.Blog]) doors.Beam[string] {
return doors.DeriveBeam(b, func(p path.Blog) string {
return p.ID
})
},
doors.RouteBeam(Post),
),
),
)
}
The second RouteMatch applies when Section == BlogPost, and RouteBeamDerive narrows the model to the ID as a read-only Beam[string]. The Post component receives just the ID instead of the full Blog source, keeping updates narrower: going from one post to another keeps Post mounted and only its Bind re-renders.
-
Create the page components:
// segments/blog/index.gox
elem Index(p doors.Source[path.Blog]) {
<h1>Blog Index</h1>
}
// segments/blog/post.gox — receives Beam[string] (the ID)
elem Post(id doors.Beam[string]) {
<h1>Post: ~(id.Bind(elem(v string) { ~(v) }))</h1>
}
-
Add the segment's routes to the router in app.gox:
<>
~(doors.Route(
root.Routes(),
blog.Routes(), // new — tried in order
doors.RouteBind(components.NotFound),
))
</>
All routes nest in this one doors.Route call and render in one container. A URL that decodes into a model but matches no route inside its RouteModel falls through to the next route, so NotFound (a leaf, which always matches) stays last.
Add a New Static Asset
Use Tailwind CSS
Create a style.css at the project root:
@import "tailwindcss";
Build it to assets/style.css (which is embedded by assets/embed.go):
npx @tailwindcss/cli -i ./style.css -o ./assets/style.css
See Tailwind CLI installation for setup instructions. If using npm, add node_modules/ to .gitignore. A standalone binary is also available (slower but no npm needed).
Inline Scripts and Styles
It is perfectly fine to use inline <script> and <style> tags directly. Doors converts them into loadable, cacheable resources at render time. Inline scripts are wrapped in an anonymous async function with access to $data, $hook, $fetch, $on, and $sys. See the JavaScript docs for details.
GoX Workflow
- Write GoX source in
.gox files — this is where templates and components live.
- Use
.go files for plain Go logic (path models, embed directives, helpers).
.x.go files are auto-generated — the GoX language server keeps them up to date while you edit .gox files. Do not edit them manually.
- Run
gox fmt then gox gen (fmt first, gen second) to format and regenerate from the command line.
Running the Project
go run .
Open http://localhost:8080.
Safari on localhost: Doors uses a Secure session cookie by default, which Safari rejects on plain HTTP. Use doors.WithConf(doors.Conf{ServerSessionCookieNoSecure: true}) or set up local HTTPS.
Local HTTPS: Use mkcert for trusted self-signed certs — mkcert -install && mkcert localhost 127.0.0.1 ::1.
File Watching
Doors reloads the page automatically when it detects the server has restarted. For file watching during development, install wgo and run:
wgo -file=.go -file=.css -file=.js -file=.ts go run .
This restarts the server on file changes and the browser reloads automatically.
Less useful in agentic development — the agent typically restarts the server explicitly after changes.
Learn More