DocsLogin
Advanced Usage

Advanced Usage

Schema Composition

Compose complex schemas from smaller parts:

const addressSchema = s.object({
  street: s.string(),
  city: s.string(),
  zipcode: code
});

const userSchema = s.object({
  name: s.string(),
  address: addressSchema,
  alternateAddresses: s.array(addressSchema)
});

Conditional Content

Use unions for conditional content structures:

const contentBlockSchema = s.union(
  "type",
  s.object({
    type: s.literal("text"),
    content: s.richtext()
  }),
  s.object({
    type: s.literal("image"),
    src: s.image(),
    caption: s.string().nullable()
  }),
  s.object({
    type: s.literal("video"),
    url: s.string(),
    thumbnail: s.image().nullable()
  })
);

Core Functions

initVal(config)

Normally you do not need to use this function directly, it should be setup by the init script. Initialize Val with configuration options. Returns schema builders and configuration.

Parameters:
config.project: string

Your project identifier (org/repo). You need this to connect to admin.val.build. Run the CLI command npx val connect to start the setup process.

config.gitBranch: string

Current git branch (optional)

config.gitCommit: string

Current git commit SHA (optional)

config.defaultTheme: 'light' | 'dark'

Default theme for Val Studio

config.root: string

The relative path of the project inside the repo. Used for monorepos. Example: ./web if your NextJS project is in the web/ folder.

Returns:
{ s, c, val, config }
Example:
Example
const { s, c, val, config } = initVal({
    project: "valbuild/web",
    defaultTheme: "dark"
  });

useVal(moduleVal)

Fetch content data from a Val schema definition (server-side only).

Parameters:
moduleVal: ValModule

The module definition to fetch content for

Returns:
T
Example:
Example
const content = useVal(pageVal);

useValRoute(moduleVal, params)

Use this with page.val.ts modules that use the .route() method (client-side only).

Parameters:
moduleVal: ValModule

The module definition to fetch content for

params: Promise<Record<string, string>> | unknown

The parameters to fetch content for, used to resolve the path

Returns:
T
Example:
Example
const content = useValRoute(pageVal, params);

fetchVal(moduleVal)

Fetch content data from a Val module definition (server-side only).

Parameters:
moduleVal: ValModule

The module definition to fetch content for

Returns:
Promise<T>
Example:
Example
const content = await fetchVal(pageVal);

fetchValRoute(moduleVal, params)

Use this with page.val.ts modules that use the .route() method (server-side only).

Parameters:
moduleVal: ValModule

The module definition to fetch content for

params: Promise<Record<string, string>> | unknown

The parameters to fetch content for, used to resolve the path

Returns:
Promise<T>
Example:
Example
const content = await fetchValRoute(pageVal, params);

c.define(path, schema, data)

Define content with schema validation and default data.

Parameters:
path: string

File path identifier

schema: Schema

Schema definition

data: T

Default content data

Returns:
ValSchema<T>
Example:
Example
export default c.define("/content/page.val.ts", schema, {
    title: "Hello World"
  });

initValRsc(config, modules, nextjs)

Normally you do not need to use this function directly, it should be setup by the init script. Initialize Val for React Server Components with Next.js integration.

Parameters:
config: ValConfig

Val configuration

modules: ValModules

Val modules definition

nextjs: NextJSIntegration

Next.js integration options

Returns:
{ fetchValStega, fetchValRouteStega, fetchValRouteUrl }
Example:
Example
const { fetchValStega: fetchVal, fetchValRouteStega: fetchValRoute, fetchValRouteUrl } = initValRsc(config, valModules, {
    draftMode,
    headers,
    cookies,
  });

initValClient(config, modules, nextjs)

Normally you do not need to use this function directly, it should be setup by the init script. Initialize Val for Client Components with Next.js integration.

Parameters:
config: ValConfig

Val configuration

modules: ValModules

Val modules definition

nextjs: NextJSIntegration

Next.js integration options (optional)

Returns:
{ useVal, useValRoute, useValRouteUrl }
Example:
const { useVal, useValRoute, useValRouteUrl } = initValClient(config, valModules, {
     draftMode,
     headers,
     cookies,
   });