velite

library0.3.1jsnpmunverified

Velite is a content framework that transforms Markdown/MDX, YAML, JSON, and other files into a type-safe data layer for applications. Version 0.3.1 (released February 2025) requires Node ^18.20.0 || >=20.3.0. It provides a CLI and API to define schemas using TypeScript/Zod, generating fully typed data for frontend usage. Compared to Contentlayer, Velite is actively maintained, offers a simpler setup, and supports more file types out of the box. It uses esbuild for fast builds and is designed for modern JavaScript/TypeScript projects.

devops ai-ml

npm install velite

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VELITE

velite

devopsjavascriptv0.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'velite'

✗ const { defineConfig } = require('velite')

Velite is ESM-only since v0.3. CommonJS require will fail.

default (Velite class)

✓ import Velite from 'velite'

✗ import { Velite } from 'velite'

Default export is the main class; named export Velite does not exist.

z (Zod schema)

✓ import { z } from 'velite/zod'

✗ import { z } from 'zod'

Velite re-exports Zod types and schemas from 'velite/zod' to ensure compatibility.

type Sitemap

✓ import type { Sitemap } from 'velite'

✗ import { Sitemap } from 'velite'

Sitemap is a TypeScript type; runtime import will cause error.

Shows how to define a collection of markdown posts with a Zod schema, build, and import typed data.

// velite.config.ts import { defineConfig, s } from 'velite' export default defineConfig({ collections: { posts: { name: 'Post', pattern: 'posts/**/*.md', schema: s.object({ title: s.string(), date: s.isodate(), body: s.markdown() }) } } }) // Run: npx velite build // Then import generated data: import { posts } from '.velite' // generated file console.log(posts[0].title) // typed as string

Debug

Known issues

breakingESM-only: Node 18.20+ or 20.3+ required. CommonJS not supported.

fix

Use ESM syntax, set type:module in package.json, or use dynamic import().

affects: >=0.3.0

gotchaGenerated output is in .velite folder by default; must be added to .gitignore.

fix

Add .velite to .gitignore and ensure it's not committed.

affects: >=0.1.0

deprecatedThe s.markdown() schema is deprecated in favor of s.mdx() for MDX support.

fix

Replace s.markdown() with s.mdx() in your config.

affects: >=0.3.0

gotchaHot reload requires watching mode: npx velite dev --watch. The CLI stops after first build without --watch.

fix

Run 'npx velite dev' or add '--watch' flag.

affects: >=0.2.0

breakingConfig file must export default using defineConfig; plain object export is no longer supported.

fix

Wrap config object with defineConfig().

affects: >=0.3.0

Errors

Common errors & fixes

Cannot find module '.velite' or its corresponding type declarations.

Generated .velite folder not created or not in tsconfig paths.

fix

Run 'npx velite build' first. Then add 'paths': { '.velite/*': ['./.velite/*'] } to tsconfig.json compilerOptions.

ERR_REQUIRE_ESM: require() of ES Module velite not supported.

Using CommonJS require() to import ESM-only package.

fix

Change to import syntax, set type:module in package.json, or use .mjs extension.

TypeError: s.object is not a function

Incorrect import of 's' from velite. It's a namespace, not a function.

fix

Use 'import { s } from 'velite'' then s.object({...}).

Error: Collection 'posts' does not match any files

Pattern pattern 'posts/**/*.md' does not find files.

fix

Check that posts directory exists relative to content root, and files have .md extension.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

zodrequiredSchema validation library used to define content schemas

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zce/velite ↗

packagevelite ↗

homepagehttps://github.com/zce/velite#readme ↗