frontend

package
v0.0.0-...-d267593 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package frontend compiles a generated application's TypeScript (app/javascript/**/*.ts) to the JavaScript the browser runs, with esbuild's Go API (ADR 0049). It strips types and nothing else: every file is transformed alone, node_modules is never read and import specifiers are left exactly as written, because the browser resolves them through the import map (ADR 0029). There is no Node toolchain, and no compiler in a production binary: the compiled files live in app/javascript/dist, are embedded by the application's javascript package and served by the digested asset pipeline like any other file.

esbuild does not type-check. `forge check` runs tsc --noEmit when tsc is on PATH (typeCheckFrontend in internal/cli).

This package is tooling for the forge command line. The request-handling packages never import it (architecture_test.go enforces that).

Index

Constants

View Source
const (
	// EsbuildVersion is the pinned esbuild release in go.mod. A test fails
	// when the two differ, so the version in the ADR, the docs and the
	// generated files' header cannot drift from what is linked.
	EsbuildVersion = "0.28.2"
	// TypeScriptVersion is the exact tsc release the generated CI installs
	// and `forge check` recommends.
	TypeScriptVersion = "6.0.3"

	// SourceDir is where the application's front end lives, slash-separated.
	SourceDir = "app/javascript"
	// DistDir is the compiled output below SourceDir that the application's
	// javascript package embeds.
	DistDir = "dist"
	// EntryPoint marks a TypeScript front end: the file the layout loads.
	EntryPoint = "application.ts"
)

Variables

This section is empty.

Functions

func Build

func Build(root fs.FS, mode Mode) (map[string][]byte, error)

Build compiles every source of the application at root and returns the outputs by their path below app/javascript/dist ("application.js", "controllers/hello_controller.js"). All errors are reported, not only the first file's.

func Compile

func Compile(name string, source []byte, mode Mode) ([]byte, error)

Compile transforms one TypeScript module to an ES2022 module. name is the source's slash-separated path below app/javascript; it labels diagnostics and the source map. Imports are kept as written.

func DistName

func DistName(source string) string

DistName is the compiled file of a source: "controllers/x.ts" becomes "controllers/x.js".

func Header(name string, source, body []byte) string

Header is the first line of a Production output for the source named name (slash-separated, relative to app/javascript) with the given content, compiled to body. It carries both hashes: the source's, which tells a stale file from a fresh one, and the body's, which tells a hand-edited or truncated file from the one forge wrote.

func IsTypeScript

func IsTypeScript(root fs.FS) bool

IsTypeScript reports whether the application at root has a TypeScript front end: its entry point app/javascript/application.ts exists. An application created with `forge new --js` has application.js instead and is left alone.

func Overlay

func Overlay(dir, outDir string) (string, error)

Overlay compiles the application at dir for development, with inline source maps, into outDir and writes outDir/overlay.json: a `go build -overlay` file that makes the compiled files appear at app/javascript/dist for that build (and hides the ones whose source is gone). The working tree is not touched, so the committed production output stays as it is. It returns the overlay's path, or "" when the application has no TypeScript front end.

func ParseHeader

func ParseHeader(output []byte) (name, sourceHash string, intact, ok bool)

ParseHeader returns the source name and the source hash a Production output declares, and whether the rest of the file (after the header line) is the body whose hash the header records. ok is false for anything that does not start with forge's header.

func SourceHash

func SourceHash(source []byte) string

SourceHash is the lowercase hex SHA-256 of a source file or a compiled body, with CRLF line ends read as LF: Git on Windows (core.autocrlf) may check the same file out with either, and the hash must not flip with it.

func Sources

func Sources(root fs.FS) ([]string, error)

Sources lists the TypeScript files of the application at root: every .ts below app/javascript except declaration files (.d.ts), the dist output, the types directory and node_modules, as slash-separated paths below app/javascript, sorted. A root without app/javascript has none.

func Sync

func Sync(dir string) ([]string, error)

Sync compiles the application at dir for production into app/javascript/dist, the files its javascript package embeds. It writes a file only when its content changes (so timestamps and version control stay quiet when nothing changed) and removes compiled files whose source is gone. It returns the paths it wrote or removed, below dist, sorted. An application without a TypeScript front end is left alone.

Types

type Mode

type Mode int

Mode selects what Compile produces.

const (
	// Production output is deterministic and carries a header naming its
	// source and the source's SHA-256, which the generated application's
	// own test checks (a stale file fails `go test`).
	Production Mode = iota
	// Development output carries an inline source map instead, so the
	// browser's developer tools show the TypeScript. `forge dev` builds it
	// into a temporary overlay and never writes it to the working tree.
	Development
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL