Reference
Reference
Project structure
Where files go, how the compiler reads them, how names work across a project, and how a project grows without getting lost.
A WebFluent project is a config file and a folder of sources that the compiler reads as one program. The folders are a convention for you and your team; the compiler does not care where a declaration lives. This chapter explains how a project is laid out and read, then shows you how to add files, choose what to commit and keep a growing project in order.
In this chapter:
- the conventional layout, and which files are required;
- how the compiler merges every file into one program, and what that means for names;
- what happens to the files that are not
.wf; - how to generate starter files, what to commit, and how to organise a project as it grows.
The layout
This is the layout wf init starts from, with every kind of file a project can hold:
my-site/
├── AGENTS.md the language reference, for a coding agent (`wf init` writes it)
├── .agents/skills/, .claude/skills/
│ the writing-webfluent skill, where agents look for one (`wf init` writes it)
├── webfluent.app.json the config (see Configuration)
├── .env build-time values, not committed (see Environments)
├── src/
│ ├── App.wf the app shell and the Router
│ ├── theme.wf themes
│ ├── types.wf shared types, enums, constants, data
│ ├── api.wf services you write by hand
│ ├── api/backend/ a service `wf api add` keeps: service.wf, and generated/ from its spec
│ ├── pages/ one page per file
│ ├── components/ components
│ ├── stores/ stores
│ ├── styles.css your own stylesheets, anywhere under src/
│ ├── tilt.js your own scripts, anywhere under src/
│ ├── translations/ en.json, ar.json (with "i18n" in the config)
│ ├── posts.json data files a `data` declaration reads
│ └── about.md Markdown pages
├── public/ copied to the build's root: favicon, fonts, images
├── tests/ `test` declarations, and __snapshots__/
└── build/ what `wf build` writes (not committed)
Only two things are required: webfluent.app.json and one .wf or .wfx file under src/. Everything else is convention. The config is covered in Configuration, and .env in Environments and secrets.
One program, with no imports
The compiler reads every .wf and .wfx file under src/ and merges them into a single program. A page uses a component declared in another file, and a component uses a store, by name. There is nothing to import.
For example, a component declared in src/components/PriceCard.wf and a page in src/pages/Pricing.wf work together with no import between them. Here they are in one block:
// In src/components/PriceCard.wf
component PriceCard(_ plan: String, price: Number) {
Card {
Text(plan).bold
Text(format(price, .currency))
}
}
// In src/pages/Pricing.wf
page Pricing(path: "/pricing", title: "Pricing", description: "Plans and prices.") {
Heading("Pricing").h1
PriceCard("Team", price: 49)
}
The compiler reads App.wf (or App.wfx) first, then the rest in path order. The order matters for nothing but the order of equal things in the output.
use Store at the top of a page or component says that it reads that store. It documents the dependency for the reader and the editor; it does not scope anything, and a page reads a store by name with or without it. use of a store nothing declares is X05.
Names across a project
Because every file is one program, the namespace is global. Two components, two pages, two stores, two types or two constants with one name is an E102 error, naming both places.
The conventions that keep names apart:
- Declared names are PascalCase: pages, components, stores, types, enums, themes, services and animations.
- Constants are UPPER_SNAKE by convention:
API,PAGE_SIZE. - A page's name is its identity, not its title. Add a suffix when the name would collide with a component:
page PostPagebesidecomponent Post. - A component that one page uses can live in that page's file.
Files that are not .wf
The build reads other files too. What each becomes:
| File | Where | Becomes |
|---|---|---|
|
|
anywhere under |
bundled into |
|
|
anywhere under |
copied to |
|
|
under |
a page (Content) |
|
|
named by a |
a constant, read at build time and held to its declared type ( |
| an OpenAPI spec |
named by |
a service's contract: its types and endpoints (Call a service from its OpenAPI spec) |
| images |
named by an |
resized, hashed files and a |
|
|
the |
the locale tables (Translate a site) |
| anything |
|
copied as it is to the build's root: |
Generate a starter file
To add a page, a component or a store with the boilerplate written for you, run wf generate:
$ wf generate page Pricing
$ wf generate component PriceCard
$ wf generate store Cart
Each command writes a starter declaration in the conventional folder:
| Command | Writes |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
In a project written in .wfx, the files are .wfx. wf generate never overwrites a file: when one exists, it says so and stops. Add -d DIR to generate into a project other than the current directory.
Choose what to commit
Commit the sources and the config:
webfluent.app.jsonsrc/public/tests/, with its__snapshots__/AGENTS.mdand the skill folders, so every agent on the project reads the same reference- a service's
generated/folder:wf api checkin CI says when it is behind its spec
Leave out what the build writes and what is private. Add these lines to .gitignore:
build/
.wf-cache/
.wf-sizes.json
.env
.wf-cache/ holds resized images between builds. .wf-sizes.json records what the last build weighed, for wf build --stats to compare against. .env holds build-time values that may be private.
Organise a growing project
As a project grows, these habits keep it readable:
- Group by feature once folders get long. A
src/billing/folder that holds the billing pages, components, store and types reads better than four folders that each hold a slice of it. The compiler does not mind either way. - Put each service in one place. Write one
apiper backend, in its own file, with the types its endpoints return beside it. - Keep shared types together, in a
types.wfper area, so the editor's go-to-definition lands somewhere predictable. - Document as you declare. A
///comment above a component, a prop, an event or a type shows on hover and inwf docs, the site that documents the project's components; anexamplebeside a component is drawn there live. - Hold every file to the formatter.
wf fmt --checkin CI keeps every file in one layout (Testing).
Quick reference
| Topic | Rule |
|---|---|
| Required files |
|
| Reading order |
|
| Imports | none: every declaration is in scope by name |
|
|
documents a dependency; scopes nothing |
| Duplicate names |
|
|
|
copied to the build's root as it is |
| Starter files |
|
| Not committed |
|