@pro-laico/zap

This was created to more easily type custom JSON fields that stored values from the Atomic hook. Which culminated in a zod wrapper with utilities you can utilize across a Payload application. The main feature though is a global register that you can easily add to and pull from with type safety.

You rarely reach for @pro-laico/zap directly, since the other @pro-laico/* packages depend on it and bring it along. It's the shared schema layer underneath them: Zod, re-exported with a small registry attached as z.ap. Each package describes its data shapes once and registers them under a string ID, and those shapes flow through Payload's type generation into your project's types. You'll usually only touch it when you're building your own package on top of Atomic Payload, or registering an extra schema of your own.

Installation

pnpm add @pro-laico/zap

npm install @pro-laico/zap

yarn add @pro-laico/zap

Usage

zap is a helper, not a Payload plugin, so you don't add it to buildConfig. Instead, you import z from it (Zod, with the z.ap registry attached) and register a schema under a string ID. Other parts of your project can then look that schema, or its type, back up by ID.

import { z } from '@pro-laico/zap'

// Register a schema under a string ID
export const MySlug = z.ap.add(z.enum(['pages', 'posts']), { id: 'MySlug' })

// Look it back up elsewhere (returns the registered Zod schema)
const slug = z.ap.get('MySlug')

// Use the matching TypeScript type in an annotation
const value: z.ap.Type<'MySlug'> = 'pages'

This is exactly how the packages use it. For example, @pro-laico/styles registers the colors used by a design set:

import { z } from '@pro-laico/zap'

export const designSetColors = z.ap.add(z.array(z.object({ name: z.string(), light: z.string(), dark: z.string() })), { id: 'DesignSetColors' })

Once a schema is registered, two more helpers feed those shapes into Payload's TypeScript generation. The @pro-laico/core JSON-schema plugin spreads toJSONSchemaExtensions into Payload's typescript.schema so every registered schema becomes a generated type, and generateBlocksType describes a union of block references. The starter template wires both in:

import { jsonSchemaPlugin } from '@pro-laico/core'
import { generateBlocksType, toJSONSchemaExtensions } from '@pro-laico/zap'

export const jsonSchemaPluginConfig = jsonSchemaPlugin({
  enabled: true,
  toJSONSchemaExtensions,
  generateBlocksType,
  blocks: {
    // name → the block slugs that belong to each generated union
  },
})

After that runs, the IDs you registered with z.ap.add show up as members of the generated AtomicRegistry type, so z.ap.get(id) and z.ap.Type<id> resolve to your project's real shapes.

Exports

import { z } from '@pro-laico/zap'// Register a schema once, under a string ID, and export the schema as usual.export const DesignSetColors = z.ap.add(z.array(z.object({ name: z.string(), light: z.string(), dark: z.string() })),{ id: 'DesignSetColors' },)// Anywhere else, look it back up by ID (returns the registered Zod schema)...const colors = z.ap.get('DesignSetColors')// ...or use its generated type in an annotation:const value: z.ap.Type<'DesignSetColors'> = []

import { jsonSchemaPlugin } from '@pro-laico/core'import { generateBlocksType, toJSONSchemaExtensions } from '@pro-laico/zap'// src/plugins/jsonSchema.ts: hand it to the core plugin, which wires it// into Payload's typescript.schema for you.export const jsonSchemaPluginConfig = jsonSchemaPlugin({enabled: true,toJSONSchemaExtensions,generateBlocksType,blocks: {  // name -> the block slugs that belong to each generated union},})

import { generateBlocksType } from '@pro-laico/zap'// Describe an "ActionBlocks" type as a union of these block slugs.const definitions = {...generateBlocksType({ name: 'ActionBlocks', refs: ['redirect', 'sendEmail', 'toast'] }),}// -> { ActionBlocks: { oneOf: [{ items: { oneOf: [...] } }] } }

Related