Table of contents

- Installation
- Getting started
- Schema types:
- String
- Number
- Boolean
- Nullable
- Array
- Record
- Router
- Object
- Rich text
- Image
- keyOf
- Route

Installation

$3

If you're starting from scratch, the easiest way to get up and running with Val and NextJS is to use npm (or similar) create script:

``sh
npm create @valbuild
`

$3

- Make sure you have NextJS (version 14 or higher) installed

- Install the packages:

`sh
npm install @valbuild/core@latest @valbuild/next@latest
`

- Optionally, but recommend add the eslint-plugin package:

`sh
npm install -D @valbuild/eslint-plugin@latest
`

- Run the init script:

`sh
npx @valbuild/init@latest
`

$3

It is also possible to setup Val using the manual configuration guide.

Additional setup

- If you have a monorepo, or have a project where the project is located in a subdirectory relative to the github repository see the monorepos section
- See formatting published content if you use prettier (or similar) Val to do it as well.
- If you want editors to update content in production, read up on how to setup remote mode.

Getting started

$3

Content in Val is always defined in .val.ts (or .js) files.

NOTE: the init script will generate an example Val content file (unless you opt out of it).

Val content files are _evaluated_ by Val, therefore they need to abide a set of requirements.
If you use the eslint plugins these requirements will be enforced. You can also validate val files using the @valbuild/cli: npx -p @valbuild/cli val validate.

For reference these requirements are:

- they must export a default content definition (c.define) where the first argument equals the path of the file relative to the val.config file; and
- they must be declared in the val.modules file; and
- they must have a default export that is c.define; and
- they can only import Val related files or types (using import type { MyType } from "./otherModule.ts")

$3

`ts
// ./examples/val/example.val.ts
import { s / s = schema /, c / c = content / } from "../../val.config";

/**
* This is the schema for the content. It defines the structure of the content and the types of each field.
*/
export const schema = s.object({
/**
* Basic text field
*/
text: s.string(),
});

/**
* This is the content definition. Add your content below.
*
* NOTE: the first argument is the path of the file.
*/
export default c.define("/examples/val/example.val.ts", schema, {
text: "Basic text content",
});
`

$3

Once you have created your Val content file, it must be declared in the val.modules.ts (or .js) file in the project root folder.

Example:

`ts
import { modules } from "@valbuild/next";
import { config } from "./val.config";

export default modules(config, [
// Add your modules here
{ def: () => import("./examples/val/example.val") },
]);
`

$3

In client components you can access your content with the useVal hook:

`tsx
// ./app/page.tsx
"use client";
import { useVal } from "../val/val.client";
import exampleVal from "../examples/val/example.val";

export default function Home() {
const { text } = useVal(exampleVal);
return

{text}

;
}
`

$3

In React Server components you can access your content with the fetchVal function:

`tsx
// ./app/page.tsx
"use server";
import { fetchVal } from "../val/val.rsc";
import exampleVal from "../examples/val/example.val";

export default async function Home() {
const { text } = await fetchVal(exampleVal);
return

{text}

;
}
`

Remote Mode

Enable remote mode to allow editors to update content online (outside of local development) by creating a project at admin.val.build.

NOTE: Your content remains yours. Hosting content from your repository does not require a subscription. However, to edit content online, a subscription is needed — unless your project is a public repository or qualifies for the free tier. Visit the pricing page for details.

WHY: Updating code involves creating a commit, which requires a server. We offer a hosted service for simplicity and efficiency, as self-hosted solutions takes time to setup and maintain. Additionally, the val.build team funds the ongoing development of this library.

Remote Mode Configuration

Once your project is set up in admin.val.build, configure your application to use it by setting the following:

$3

- VAL_API_KEY: This is the API key used to authenticate server side API requests. You can find it under Settings in your project on admin.val.build.
- VAL_SECRET: In addition to the VAL_API_KEY, you need to generate a random secret to secure communication between the UX client and your Next.js application. You can use any random string for this, but if you have openssl installed you can run the following command: openssl rand -hex 16

$3

Set these properties in the val.config file:

- project: The fully qualified name of your project, formatted as /.
- gitBranch: The Git branch your application uses. For Vercel, use VERCEL_GIT_COMMIT_REF.
- gitCommit: The current Git commit your application is running on. For Vercel, use VERCEL_GIT_COMMIT_SHA.
- root: Optional. The path to the val.config file. Typically empty or undefined. If the project folder is under web, root would be: /web.

$3

`ts
import { initVal } from "@valbuild/next";

const { s, c, val, config } = initVal({
project: "myteam/myproject",
//root: "/subdir", // only required for monorepos. Use the path where val.config is located. The path should start with /
gitBranch: process.env.VERCEL_GIT_COMMIT_REF,
gitCommit: process.env.VERCEL_GIT_COMMIT_SHA,
});

export type { t } from "@valbuild/next";
export { s, c, val, config };
`

Formatting published content

If you are using prettier or another code formatting tool, it is recommended to setup formatting of code after changes have been applied.

Setting up formatting using Prettier

- Install prettier as RUNTIME dependency, by moving the prettier dependency from devDependencies to dependencies. The reason you need to do this, is that Val will be using it at runtime in production, and it has to be part of your build for this to work.
- Optionally create a .prettierrc.json file unless you have one already. We recommend doing this, so that you can be sure that formatting is applied consistently in both your development environment and by Val. You can set this to be an empty object, if you are want to keep using prettiers defaults:

`json
{}
`

- Add a formatter to the /val/val.server:

`ts
formatter: (code: string, filePath: string) => {
return prettier.format(code, {
filepath: filePath,
...prettierOptions, // <- use the same rules as in development
} as prettier.Options);
},
`

Unless you have any modifications in your val.server file, the complete file should now look like this:

`ts
import "server-only";
import { initValServer } from "@valbuild/next/server";
import { config } from "../val.config";
import { draftMode } from "next/headers";
import valModules from "../val.modules";
import prettier from "prettier";
import prettierOptions from "../.prettierrc.json";

const { valNextAppRouter } = initValServer(
valModules,
{ ...config },
{
draftMode,
formatter: (code: string, filePath: string) => {
return prettier.format(code, {
filepath: filePath,
...prettierOptions, // <- use the same rules as in development
} as prettier.Options);
},
},
);

export { valNextAppRouter };
`

You should now be able to hit the save button locally and see prettier rules being applied.

Other formatters

Val is formatter agnostic, so it is possible to use the same flow as the one described for prettier above to any formatter you might want to use.

NOTE: this will be applied at runtime in production so you need make sure that the formatting dependencies are in the dependencies section of your package.json

Monorepos

Val supports projects that are not under the root path in GitHub, and therefore monorepos.
To configure your project for monorepos, you can use the root parameter described in the config section.

Schema types

String

`ts
import { s } from "./val.config";

s.string(); // <- Schema
`

Number

`ts
import { s } from "./val.config";

s.number(); // <- Schema
`

Boolean

`ts
import { s } from "./val.config";

s.boolean(); // <- Schema
`

Nullable

All schema types can be nullable (optional). A nullable schema creates a union of the type and null.

`ts
import { s } from "./val.config";

s.string().nullable(); // <- Schema
`

Array

`ts
s.array(t.string()); // <- Schema
`

Record

The type of s.record is Record.

It is similar to an array, in that editors can add and remove items in it, however it has a unique key which can be used as, for example, the slug or as a part of an route.

NOTE: records can also be used with keyOf.

`ts
s.record(t.number()); // <- Schema>
`

Router

The router schema is a convenient shorthand for creating a record with router configuration. It combines s.record() and .router() into a single call.

`ts
import { s, c, nextAppRouter } from "../val.config";

const pageSchema = s.object({ title: s.string() });

// Using s.router() - shorthand
const pagesSchema = s.router(nextAppRouter, pageSchema);

// Equivalent to:
const pagesSchema = s.record(pageSchema).router(nextAppRouter);
`

$3

`ts
import { s, c, nextAppRouter } from "../val.config";

const pageSchema = s.object({ title: s.string() });

// NOTE: to use router(nextAppRouter) - the module must be a sibling of the page.tsx
export default c.define(
"/app/[slug]/page.val.ts",
s.router(nextAppRouter, pageSchema),
{
"/test-page": {
// This is the full pathname of the page - it must match the pattern of the Next JS route
title: "Test page",
},
},
);
`

Object

`ts
s.object({
myProperty: s.string(),
});
`

#### Page router (using .router() method)

You can configure Val to track your page structure and display content as navigable web pages in the editor interface.

For editors, this creates an intuitive page-based editing experience where they can navigate through your site structure and edit content directly within the context of each page.

You can use the .router method on record to achieve this.

When using the .router with the nextAppRouter, it will automatically generate routes based on your record keys and integrate seamlessly with Next.js App Router conventions.

#### Example:

`ts
import { s, c, nextAppRouter } from "../val.config";

const pageSchema = s.object({ title: s.string() });
const pagesSchema = s.record(pageSchema).router(nextAppRouter);

// NOTE: to use router(nextAppRouter) - the module must be a sibling of the page.tsx. In other words it must with page.val.ts or page.val.js
export default c.define("/app/[slug]/page.val.ts", pageSchema, {
"/test-page": {
// This is the full pathname of the page - it must match the pattern of the Next JS route of the page.tsx you are consuming this from
title: "Test page",
},
});
`

To consume a page route from a NextJS "page component", it is recommended you use fetchValRoute or useValRoute.

NOTE: to be refactor proof (i.e. not break when changing the route), you should always provide the params of the NextJS page component.

#### Example fetchValRoute

`ts
export default async function MyPage({ params }: { params:
Promise<{ slug: string }> // use params: Promise if this page route has no params
}) {
const page = await fetchValRoute(pageVal, params)
return
}
`

$3

You can customize how records are displayed in the Val editor interface by using the .render method on record. This allows you to control how individual record items appear in the editor's preview.

The only currently supported layout is list, which provides a customizable list view for record previews.

#### Example

`ts
const pagesSchema = s
.record(s.object({ title: s.string(), image: s.image() }))
.router(nextAppRouter)
.render({
layout: "list", // Use list layout for record preview
select({ key, val }) {
return {
// Capitalize the first letter of the key for display
title: key?.[0]?.toUpperCase() + key?.slice(1),
// Show the image from the record
image: val.image,
};
},
});
`

RichText

RichText in Val represented both in code and to the editors as semantic html5.

This means that content will be accessible and according to spec out of the box. The flip-side is that Val will not support RichText that includes elements that is not part of the html 5 standard.

This opinionated approach was chosen since rendering anything, makes it hard for developers to maintain and hard for editors to understand.

$3

`ts
s.richtext({
// options
});
`

$3

To initialize some text content using a RichText schema, you can use follow the example below:

`ts
import { s, c } from "./val.config";

export const schema = s.richtext({
// styling
style: {
bold: true, // enables bold
italic: true, // enables italic text
lineThrough: true, // enables line/strike-through
},
// tags:
block: {
//ul: true, // enables unordered lists
//ol: true, // enables ordered lists
// headings:
h1: true,
h2: true,
// h3: true,
// h4: true,
// h5: true,
// h6: true
},
inline: {
//a: true, // enables links
//img: true, // enables images
},
});

export default c.define("/src/app/content", schema, [
{
tag: "p",
children: ["This is richtext"],
},
{
tag: "p",
children: [{ tag: "span", styles: ["bold"], children: ["Bold"] }, "text"],
},
]);
`

$3

You can use the ValRichText component to render content.

`tsx
"use client";
import { ValRichText } from "@valbuild/next";
import contentVal from "./content.val";
import { useVal } from "./val/val.client";

export default function Page() {
const content = useVal(contentVal);
return (



theme={{
style: {
bold: "font-bold", // <- maps bold to a class. NOTE: tailwind classes are supported
},
//
}}
content={content}
/>



);
}
`

#### ValRichText: theme property

To add classes to ValRichText you can use the theme property:

`tsx
theme={{
p: "font-sans",
// etc
}}
content={content}
/>
`

NOTE: if a theme is defined, you must define a mapping for every tag that the you get. What tags you have is decided based on the options defined on the s.richtext() schema. For example: s.richtext({ style: { bold: true } }) requires that you add a bold theme.

`tsx
theme={{
h1: "text-4xl font-bold",
bold: "font-bold",
img: null, // either a string or null is required
}}
content={content}
/>
`

NOTE: the reason you must define themes for every tag that the RichText is that this will force you to revisit the themes that are used if the schema changes. The alternative would be to accept changes to the schema.

$3

Vals RichText type maps RichText 1-to-1 with semantic HTML5.

If you want to customize / override the type of elements which are rendered, you can use the transform property.

`tsx
transform={(node, _children, className) => {
if (typeof node !== "string" && node.tag === "img") {
return (



);
}
// if transform returns undefined the default render will be used
}}
content={content}
/>
`

$3

The RichText type is actually an AST (abstract syntax tree) representing semantic HTML5 elements.

That means they look something like this:

`ts
type RichTextNode = {
tag:
| "img"
| "a"
| "ul"
| "ol"
| "h1"
| "h2"
| "h3"
| "h4"
| "h5"
| "h6"
| "br"
| "p"
| "li"
| "span";
classes: "bold" | "line-through" | "italic"; // all styling classes
children: RichTextNode[] | undefined;
};
`

$3

The RichText type maps 1-to-1 to HTML.
That means it is straightforward to build your own implementation of a React component that renders RichText.

This example is a simplified version of the ValRichText component.
You can use this as a template to create your own.

NOTE: before writing your own, make sure you check out the theme and transform properties on the ValRichText - most simpler cases should be covered by them.

`tsx
export function ValRichText({
content,
}: {
content: RichText;
}) {
function build(
node: RichTextNode,
key?: number,
): JSX.Element | string {
if (typeof node === "string") {
return node;
}
// you can map the classes to something else here
const className = node.classes.join(" ");
const tag = node.tag; // one of: "img" | "a" | "ul" | "ol" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "br" | "p" | "li" | "span"

// Example of rendering img with MyOwnImageComponent:
if (tag === "img") {
return ;
}
return React.createElement(
tag,
{
key,
className,
},
"children" in node ? node.children.map(build) : null,
);
}
return

;
}
type MyRichTextOptions = AnyRichTextOptions; // you can reduce the surface of what you need to render, by restricting the options in s.richtext(options)
`

Image

$3

`ts
s.image();
`

$3

Local images must be stored under the /public/val folder.

`ts
import { s, c } from "../val.config";

export const schema = s.image();

export default c.define("/image", schema, c.image("/public/myfile.jpg"));
`

NOTE: This will not validate, since images requires width, height and mimeType. You can fix validation errors like this by using the CLI or by using the VS Code plugin.

$3

The ValImage component is a wrapper around next/image that accepts a Val Image type.

You can use it like this:

`tsx
const content = useVal(contentVal); // schema of contentVal: s.object({ image: s.image() })

return ;
`

$3

Images are transformed to object that have a url property which can be used to render them.

Example:

`tsx
// in a Functional Component
const image = useVal(imageVal);

return ;
`

Union

The union schema can be used to create either "tagged unions" or a union of string literals.

$3

A tagged union is a union of objects which all have the same field (of the same type). This field can be used to determine (or "discriminate") the exact type of one of the types of the union.

It is useful when editors should be able to chose from a set of objects that are different.

Example: let us say you have a page that can be one of the following: blog (page) or product (page). In this case your schema could look like this:

`ts
s.union(
"type", // the key of the "discriminator"
s.object({
type: s.literal("blogPage"), // <- each type must have a UNIQUE value
author: s.string(),
// ...
}),
s.object({
type: s.literal("productPage"),
sku: s.number(),
// ...
}),
); // <- Schema<{ type: "blogPage", author: string } | { type: "productPage", sku: number }>
`

Union Schema: union of string literals

You can also use a union to create a union of string literals. This is useful if you want a type-safe way to describe a set of valid strings that can be chosen by an editor.

`ts
s.union(
s.literal("one"),
s.literal("two"),
//...
); // <- Schema<"one" | "two">
`

KeyOf

You can use keyOf to reference a key in a record of a Val module.

NOTE: currently you must reference keys in Val modules, you cannot reference keys of values nested inside a Val module. This is a feature on the roadmap.

`ts
const schema = s.record(s.object({ nested: s.record(s.string()) }));

export default c.define("/keyof.val.ts", schema, {
"you-can-reference-me": {
// <- this can be referenced
nested: {
"but-not-me": ":(", // <- this cannot be referenced
},
},
});
`

$3

`ts
import otherVal from "./other.val"; // NOTE: this must be a record

s.keyOf(otherVal);
`

$3

$3

`tsx
const article = useVal(articleVal); // s.object({ author: s.keyOf(otherVal) })
const authors = useVal(otherVal); // s.record(s.object({ name: s.string() }))

const nameOfAuthor = authors[articleVal.author].name;
`

Route

The route schema represents a string that references a route path in your application. It can be used with include and exclude patterns to constrain which routes are valid.

$3

`ts
s.route(); // <- Schema
`

$3

You can use include and exclude to constrain valid routes using regular expressions:

`ts
// Only allow API routes
s.route().include(/^\/api\//);

// Exclude admin routes
s.route().exclude(/^\/admin\//);

// Combine both: API routes except internal ones
s.route()
.include(/^\/api\//)
.exclude(/^\/api\/internal\//);
`

Pattern semantics:

- If only include is set: route must match the include pattern
- If only exclude is set: route must NOT match the exclude pattern
- If both are set: route must match include AND must NOT match exclude

$3

Routes are validated against router modules (records with .router() or s.router()). The route value must exist as a key in one of your router modules.

`ts
import { s, c } from "../val.config";

const linkSchema = s.object({
label: s.string(),
href: s.route().include(/^\//), // Only allow routes starting with /
});

export default c.define("/components/link.val.ts", linkSchema, {
label: "Home",
href: "/", // This must exist in a router module
});
`

Custom validation

All schema can use the validate method to show custom validation errors to editors.

Example

`ts
s.string().validate((val) => {
if (val.startsWith("something")) {
return "Cannot have something in this string";
}
return false; // no validation error
});
``

Get in touch

Join us on discord to get help or give us feedback.