File conventions

A representative site looks like this:

package.json
package-lock.json
tsconfig.json
site.yaml
pages/
├── layout.tsx
├── page.yaml                         → /
└── 01_about/
    ├── layout.tsx                    → wraps this branch
    ├── page.yaml                     → /about
    └── 01_getting-started/
        └── page.json                 → /about/getting-started
templates/
└── default.tsx
public/
└── style.css

Project files

package.json declares @carl.fyi/tinyjs, the Node.js version, and the commands used to serve and build the site. Keep the generated package-lock.json with it so installs remain reproducible.

A tsconfig.json is recommended for type-checking layouts and templates. Configure it to use @carl.fyi/tinyjs as the JSX import source and include the TSX files under pages/ and templates/.

Site configuration

The root configuration may be named site.yaml, site.yml, or site.json. Provide exactly one. Multiple matching files are an error.

The configuration is a complete structured document. TinyJS does not use frontmatter or a section-delimiter format.

Pages

Each route directory may contain one of page.yaml, page.yml, or page.json. Providing more than one page document at the same location is an error.

The root pages/page.* maps to /. Nested directories become nested URL segments.

Templates

The template field in a page document selects a matching TSX module in templates/. A page with template: default uses templates/default.tsx.

Layouts

A layout.tsx inside pages/ wraps the page template for its route branch. Layouts nest according to the directory tree, from the nearest route directory back to the root.

Public files

Files in public/ are copied as public assets. Use the asset() helper supplied to layouts and templates when creating asset URLs that need to respect a site base path.