Frontmatter

Frontmatter directives and their syntax.

Frontmatter is the block between two --- lines at the top of a .slurp file. The delimiters must be at column 1. Every directive is optional, and so is the block.

---
using "@components/ProductCard"
using type { Product } from "@types/shop"

type Address {
  street: string
  city: string
}

props {
  product: Product
  featured: bool = false
}

middleware "auth/require-login"

section {
  name: "Featured"
  settings { heading: text = "Featured products" }
}
---

The complete list

Directive	Syntax	Effect
using	using "@components/Card" or using "./Card" as Renamed	Makes a component resolvable
using type	using type { Post, Author } from "@types/content"	Tooling only, no render effect
type	type Post { id: string views?: number }	Recorded as raw strings, NEVER enforced
props	props { title: string count?: number featured: bool = false }	Declares the prop contract and any defaults
middleware	middleware "auth" or middleware auth	Records a name, nothing more
section { }	see Schemas	Declares the editor surface for a section
block { }	see Schemas	Same, for a reusable theme block

Directives may appear in any order, and repeated using, type and props statements accumulate. A second section { } or a second block { } is an InvalidFrontmatter error; both may appear in the same file.

Unknown statements are silently skipped. A misspelled directive produces no diagnostic at all.

---
layout: "@layouts/base"
totallyMadeUp foo bar
---

Both lines are accepted and ignored. There is no layout directive; use the {layout "..."} block tag in the body. InvalidFrontmatter fires only on a MALFORMED known directive, never on an unrecognised one.

using

using "@components/Button"
using "../../shared/Footer"
using "@components/Button" as PrimaryButton

The local name is the alias if one is given, otherwise the last path segment. So using "@components/Card" introduces Card, which is what makes <Card /> resolve.

@-prefixed paths are registry keys the host resolves. The CLI resolves @components/X and @layouts/X against the project directory.

An unresolvable import is not an error. The component renders a placeholder:

<div data-slurp-component="Card" data-slurp-props="{&quot;title&quot;:&quot;Bo&quot;}"></div>

A typo in an import path therefore looks like a clean build with a missing card. Grep the output for data-slurp-component when something is unexpectedly absent.

using type

using type { Product, Review } from "@types/shop"

Imports type names for editor tooling. It introduces no component and has no effect on rendering. The from keyword is required; omitting it is InvalidFrontmatter.

type

type CartItem {
  id: string
  name: string
  price: number
  quantity?: number
}

Declares a shape for use in props or a {fetch} type hint. A ? marks a field optional.

Type expressions are stored as raw strings and are never checked, at parse time or at render time. TypeMismatch is declared in the error enum and never emitted. The names are for humans and for editor tooling.

props

props {
  title: string
  count?: number
  featured: bool = false
}

name · required

The prop name. A ? immediately after it marks the prop optional.

type · required

A type expression, stored as a raw string. Append [] for an array.

= default

Optional. The expression is evaluated in the caller’s scope when the prop is not passed.

Prop types and requiredness are recorded and NEVER validated at render time, so a missing required prop is simply null. MissingRequiredProp and UnknownProp are both declared and never emitted; passing a prop the component never declared is not an error either.

A type expression runs to the end of the line. It terminates at a newline, a comma, a =, or the closing brace. So several space-separated declarations on one line collapse into a single prop whose type expression swallows the rest:

props { a: string  b: number  c: bool }   {* ONE prop named a *}
props { a: string, b: number, c: bool }   {* three props *}
props {
  a: string
  b: number
}                                          {* three props, the clearest form *}

Adding a = default also terminates the type expression, so the one-line form happens to work once every prop has a default. Because types are never enforced, the collapse is otherwise invisible at render time. Write one prop per line anyway: the collapsed form is what the editor tooling reads back.

Defaults are evaluated in the caller’s scope

components/Card.slurp

---
props { n?: number = count5 }
---
<div>${ n }</div>

Rendered from a page whose context has count5 = 5, <Card /> produces <div>5</div>. The default expression is resolved where the component was written into the page, not inside the component.

middleware

middleware "auth/session-check"
middleware auth

Both the quoted and the bare form are accepted, and both only RECORD a name.

Middleware is a compile option, not a filename or frontmatter convention. What makes a file middleware is CompileOptions.is_middleware, supplied by whoever invokes the compiler. On the CLI that is the --middleware <DIR> flag.

Without it, every file is treated as non-middleware, so a correct middleware file reports MiddlewareScopeViolation for its request.* reads, and a broken one is never checked at all.

Inside a file compiled as middleware, the scope rules invert: request.*, {redirect} and {next} become legal, and the only path roots allowed are request, env and loop. Reading any other root there is MiddlewareScopeViolation.

section { } and block { }

These declare a typed editor surface. The grammar is large enough to have its own page: see Schemas.

section, settings, blocks, name, max and max_per_page are CONTEXTUAL keywords. They lex as ordinary identifiers and gain meaning only at that exact structural position, so a template using any of them as a prop name or a type name is unaffected. A section statement is recognised only when a { follows it immediately.

env and secrets

env.* is readable from a template, with one hard restriction enforced at compile time:

<script>const k = ${ env.SLURP_SECRET_API_KEY | js };</script>

error[SecretEnvInTemplate]: env.SLURP_SECRET_API_KEY must not be accessed
in templates; use server-side data binding instead

The gate covers three cases, all under the same code:

Written	Result
env.PUBLIC_URL	fine
env.SLURP_SECRET_X or env["SLURP_SECRET_X"]	env.SLURP_SECRET_X must not be accessed in templates
env[someKey]	env[...] must be indexed by a literal key so secret access can be checked at compile time

A non-constant key is refused because it could resolve to a secret name. Read the secret on the server and pass only a derived, non-secret value through the render context.