56 lines
1.8 KiB
Markdown
56 lines
1.8 KiB
Markdown
# ADR-003: SSR Strategy - Go Templates with Embedded Browser Scripts
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
Document pages must be readable quickly and safely while still supporting
|
|
editing, authentication, comments, offline caching, and real-time updates.
|
|
|
|
## Decision
|
|
Go `html/template` renders complete HTML pages. The server embeds and serves
|
|
small framework-free browser scripts for progressive enhancement.
|
|
|
|
### Implementation Details
|
|
|
|
1. **Server Rendering**:
|
|
- Go handlers query document and account data
|
|
- Goldmark parses Markdown to HTML server-side
|
|
- `html/template` renders complete pages
|
|
- Pages are readable before JavaScript executes
|
|
|
|
2. **Browser Enhancement**:
|
|
- Embedded scripts handle editing, comments, authentication, offline cache,
|
|
service-worker behavior, and WebSocket updates
|
|
- Native browser APIs are preferred over a client framework
|
|
- There is no separate SPA route or frontend build pipeline
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- Fast first contentful paint
|
|
- Auto-escaped templates
|
|
- One deployable application artifact
|
|
- Small browser payloads and no Node build dependency
|
|
- Interactive features stay close to their HTTP endpoints
|
|
|
|
### Negative
|
|
- Browser modules need direct DOM event handling
|
|
- Shared UI abstractions require deliberate maintenance
|
|
- More complex browser interactions need focused integration tests
|
|
|
|
## Alternatives Considered
|
|
|
|
### Separate Hydrated SPA
|
|
- **Pros**: Component framework and client-side routing
|
|
- **Cons**: Duplicates UI paths and introduces a second toolchain
|
|
- **Rejected**: The server-rendered UI already supports the required behavior
|
|
|
|
### Embedded JS Runtime
|
|
- **Pros**: Isomorphic rendering
|
|
- **Cons**: Larger binary and additional security surface
|
|
- **Rejected**: Go templates are simpler
|
|
|
|
## References
|
|
- Go `html/template`: https://pkg.go.dev/html/template
|