# Velite: a build step that turns a content folder into typed data > Velite reads Markdown, MDX, YAML and JSON files through a Zod schema and writes JSON, an entry file and TypeScript declarations, so a content folder becomes a typed data layer with no runtime dependency. It is MIT licensed and framework agnostic, and the trade is that content and code are validated at build time rather than at request time. **zce/velite** — Turns Markdown / MDX, YAML, JSON, or others into app's data layer with Zod schema. - Repository: https://github.com/zce/velite - Website: http://velite.js.org - Stars: 824 · Forks: 44 - Language: TypeScript - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/zce-velite ## Content as build input rather than a runtime dependency Velite is a tool for building a type-safe data layer, turning Markdown, MDX, YAML, JSON or other files into the application's data layer with a Zod schema. The framing on the homepage puts it in the content layer and data layer family, and the topic tags list contentlayer, datalayer, headless-cms, markdown, mdx and zod. The architectural choice is the important part. Velite runs as a build step. You point it at a content directory, it parses and validates every file against a schema you write, and it writes out JSON, an entry file and TypeScript declaration files. The application then imports those outputs as ordinary modules. The result is that your content ships with your application and carries types. A blog post frontmatter that is missing a date or has a category that is not in your union type is a build failure rather than an undefined at runtime. The alternative to this is a content framework that parses markdown in the browser or on the server, which means shipping a parser, a schema validator and the content to every visitor, and it means the content is only valid if a page happens to be requested. The naming is explained in the README: Velite comes from the English word elite, and Velite itself was the code name for Napoleon's elite army. The audience is developers with content in the repository. The README notes you may need a real-world project to start quickly, and points to a fork of the shadcn-ui taxonomy project as an example, along with StackBlitz projects for a basic setup and a Next.js setup that you can try in the browser. ## The workflow is four steps The easy to use feature is described in one sentence: move your contents into a content folder, define collections schema, run velite, then use the output data in your application. That is the whole flow, and each step has a design decision in it. The content folder convention means the tool has a default location and knows where to look, and both the input and output directories can be customized. The collections schema is a Zod schema, so the shape of each content type is expressed in the validation library you already use for form data, and the type inference for TypeScript comes from the same source. The run step is a CLI. The package.json declares the binary and the published package name: ```json "name": "velite", "version": "0.4.0", "bin": "./bin/velite.js", ``` The description of the workflow names the command as velite, and the README links the npm package page for it. The output step is where the framework agnostic claim comes from. The outputs are JSON, an entry file and DTS, and the README states that this gives out of the box support for any JavaScript framework or library. The entry file is the piece worth understanding: it is a single module that re-exports everything, so your application imports one path rather than reaching into a directory of generated JSON. Because the output is plain data, there is no runtime dependency at all. The light-weight feature says it chooses more native APIs instead of bloated NPM modules, with less runtime dependencies so it is fast and efficient. The runtime dependencies in the package.json are only used by the build: @mdx-js/mdx for MDX, esbuild for bundling, sharp for image processing and terser for minification. None of that ends up in your bundle. The repository layout supports the same idea. There is a packages directory, a pnpm-workspace.yaml, a src directory, a bin directory, a test directory, an examples directory with basic, nextjs and vite setups, and a docs directory with its own dev and build scripts. The test script runs the node test runner over files in test/. ## What a Velite schema can validate and transform The feature list names the built-in capabilities, and the more interesting ones are the extension points. Built in are Markdown and MDX, YAML and JSON support, relative file and image processing, and schema validation. The relative file handling is worth pausing on, because it is what makes images work: a markdown file with a relative image path gets processed, and the output can carry the hashed or copied asset path rather than the original relative one, so the content folder is self-contained. The extension story is where the tool is genuinely different from a simple frontmatter parser. Support any file types by custom loaders. Custom field validation and transform by custom schema with a parser context function. And any output formats by hooks. Those three together mean the data layer is not limited to the built-in formats, and the schema is a place where you can run arbitrary code per field rather than only assert a type. The parser context is the specific mechanism. A Zod schema normally validates a value. Here the value is a parsed document plus the context of where it came from, and a custom parser can use that context. In practice that means a field can be resolved relative to the file it was found in, or rejected with an error that points at the offending file. Configuration covers both the input and output directories, and the README mentions support for custom loaders and hooks as part of the configurable feature. The built-in schema set is on the roadmap as more built-in schemas, which tells you that the starting point is a hand-written schema for each collection rather than a library of ready made content types. ## Where the output ends and your framework begins The Next.js integration is the interesting case, because the roadmap says a Next.js plugin package is currently a snippet, with a link to the guide page for starting Velite with the Next.js plugin. So the integration story today is: a documented snippet that wires the Velite build into a Next.js project, rather than a maintained plugin package. The repository has an examples/nextjs directory, and there is a StackBlitz project for the same. For a Vite project there is an examples/vite directory, and the guide has a with-nextjs page. There is also a start Velite with Next.js plugin documentation page referenced from the roadmap entry, which suggests the snippet is a real, documented starting point. That tells you something about the project's shape. It is a build tool that outputs framework-neutral artifacts, and the framework wiring is documentation rather than code, which keeps the core small and the maintenance surface small. It is the opposite trade from a framework plugin that owns your build. The other side of that is that you own the wiring. The build must run before the framework build, and the output directory must be inside the tree your framework watches, and the generated files must be excluded or regenerated consistently so a stale file does not end up in a production bundle. None of that is difficult, and all of it is yours. The framework agnostic claim is worth reading carefully rather than as marketing. It means the output is JSON, an entry and declarations, and any JavaScript framework or library can consume it. It does not mean every framework has a first class integration, because for Next.js the documented path is a snippet. ## The roadmap gaps that matter for a content site The roadmap is short and honest, and reading it tells you which kind of project will be comfortable with Velite. More framework or build tool integration examples is on the list, which is a sign that the existing examples are thin rather than that the core is fragile. More built-in schemas is on the list, which again says the schemas are yours to write. A scaffolding tool is on the list, so the setup is manual today. Incremental build is on the list, and that is the one with a real cost. Turborepo is on the list, so monorepo integration is not built in. And a Next.js plugin package is on the list, with the snippet standing in for it. Incremental build deserves the attention. Without it, every run reprocesses the whole content folder, and the cost of that grows with the size of the content and with the weight of the per-file work, which for MDX means running the MDX compiler and for images means running sharp. For a documentation site with a few hundred pages that is fine. For a large collection with heavy MDX and many images, a full rebuild on every save is a real cost, and the tool does not yet have the incremental path. There is one more item on the list that is easy to misread: unit and end to end tests, with a question mark. The project is honest that it does not have its own test suite in the usual sense, even though there is a test directory and a test script that runs the node test runner over files in it. The question mark means the coverage is not where a mature project would want it. The live users list is worth a look as a signal about where the tool fits. Ark UI, Chakra UI and Park UI are named, and those are component library teams who already had content and wanted a typed data layer rather than a hosted CMS. The remaining projects are at the link to the network of dependents. None of this makes Velite a bad choice. It makes it a build-time content tool for a repository-driven site, with the sharp edges listed above. ## Licence, maintenance and how to try it before committing The licence is MIT, and the README spells it out as MIT licensed and copyright zce. The package.json declares the same, and the repository has a license file at the root. MIT means you can use it in a commercial site without obligations, which for a build tool in a company repository is the sensible default. The maintenance picture is good. The repository is not archived, the last push was on 2026-10-18, and the CI badge points at a GitHub Actions workflow running on the main branch. The release history shows v0.4.0 on 2026-06-17, v0.3.1 on 2025-12-08 and v1.0.0-alpha.3 on 2026-06-19, which tells you the project is heading towards a 1.0 and is publishing prereleases of it while the stable line is still at 0.4. The package.json version matches 0.4.0, so the alpha is a separate track. That distinction matters if you pin. A consumer on 0.4.0 gets the stable line, and the 1.0 alpha line is where the coming changes live. The fastest way to evaluate it is the two StackBlitz projects, one for a basic setup and one for Next.js, which run in the browser with no local toolchain. The README also points to a fork of the shadcn-ui taxonomy project as a realistic example, which is more useful than a hello world because it has a real content structure. For a first local run, the sequence is short. Put the content in a content folder, write a collections schema with Zod, run the velite command, and then import the generated entry in your application. The rest is wiring the build to run before your framework build. One last practical note. The generated output is data, and like any generated artifact it will be diff noise in your repository if it is committed by hand. The project does not document a recommended gitignore pattern for the output, so decide early whether the output is committed or built in CI, because regenerating a large entry file on every content change produces a review that nobody reads. ## Conclusion Adopt Velite if your application keeps its content in the repository and wants a typed, validated data layer without a hosted CMS and without pulling a content framework into the runtime. Do not adopt it if editors outside your team need to publish content on a schedule, since the source of truth is a folder in git. Verify first that your existing content fits the Zod schema you write, that the generated output is regenerated in CI rather than committed by hand, and that the roadmap gaps, incremental build and Turborepo support, do not block your workflow. ## FAQ ### What does Velite do and who is it for? Velite is a build tool that turns Markdown, MDX, YAML, JSON or other files into an application's data layer using Zod schemas, outputting JSON, an entry file and TypeScript declarations. It suits developers who keep content in the repository and want a typed data layer without a hosted CMS. ### How do I start using Velite? Move your contents into a content folder, define a collections schema, run `velite`, then use the output data in your application. Both the input and output directories can be customized, and the package is published on npm as velite. ### Does Velite add anything to my runtime bundle? No. The runtime dependencies in the package.json are build-time only, including @mdx-js/mdx, esbuild, sharp and terser. The outputs are JSON, an entry file and declaration files, which the README describes as giving out of the box support for any JavaScript framework or library. ### Can Velite read file types other than Markdown and YAML? Yes. The feature list names support for any file types by custom loaders, custom field validation and transform by custom schema with a parser context function, and any output formats by hooks. ### Is there a Next.js plugin for Velite? Not as a maintained package yet. The roadmap lists a Next.js plugin package as a goal and notes that it is currently a snippet, with the guide page for starting Velite with the Next.js plugin linked from the roadmap entry. ### What license is Velite released under? MIT, declared in the package.json and with the license file at the repository root, credited to zce. ## Sources - [License: MIT](https://github.com/zce/velite/blob/main/LICENSE) - [Project website](http://velite.js.org) - [README](https://github.com/zce/velite/blob/main/README.md) - [Releases](https://github.com/zce/velite/releases) - [zce/velite on GitHub](https://github.com/zce/velite) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zce-velite