Quick Start
Installation
Prerequisites
- Node.js version 18.17 or higher, LTS version is recommended.
- macOS, Windows, and Linux are supported.
$ npm install velite -D
$ pnpm add velite -D
$ yarn add velite -D
$ bun add velite -D
Velite is an ESM-only package
Don't use require()
to import it, and make sure your nearest package.json
contains "type": "module"
, or change the file extension of your relevant files like velite.config.js
to .mjs
/.mts
. Also, inside async CJS contexts, you can use await import('velite')
instead.
Define Collections
Create a velite.config.js
file in the root directory of your project to define collections config:
import { defineConfig, s } from 'velite'
// `s` is extended from Zod with some custom schemas,
// you can also import re-exported `z` from `velite` if you don't need these extension schemas.
export default defineConfig({
collections: {
posts: {
name: 'Post', // collection type name
pattern: 'posts/**/*.md', // content files glob pattern
schema: s
.object({
title: s.string().max(99), // Zod primitive type
slug: s.slug('posts'), // validate format, unique in posts collection
// slug: s.path(), // auto generate slug from file path
date: s.isodate(), // input Date-like string, output ISO Date string.
cover: s.image(), // input image relative path, output image object with blurImage.
video: s.file().optional(), // input file relative path, output file public path.
metadata: s.metadata(), // extract markdown reading-time, word-count, etc.
excerpt: s.excerpt(), // excerpt of markdown content
content: s.markdown() // transform markdown to html
})
// more additional fields (computed fields)
.transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))
},
others: {
// other collection schema options
}
}
})
For more information about Velite extended field schemas, see Velite Schemas.
TIP
Config file supports TypeScript & ESM & CommonJS. you can use the full power of TypeScript to write your config file, and it's recommended strongly.
Create Contents Files
Add your creative content into the content
directory, like this:
root
+├── content
+│ ├── posts
+│ │ └── hello-world.md
+│ └── others
+│ └── other.yml
├── public
├── package.json
└── velite.config.js
content/posts/hello-world.md
---
title: Hello world
slug: hello-world
date: 1992-02-25 13:22
cover: cover.jpg
video: video.mp4
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse
![some image](img.png)
[link to file](plain.txt)
Build Contents by Velite
Run velite
command in terminal, then Velite will build the contents and related files.
$ npx velite
$ pnpm velite
$ yarn velite
$ bun velite
Then you will get the following output:
root
+├── .velite
+│ ├── posts.json # posts collection output
+│ ├── others.json # others collection output
+│ ├── index.d.ts # typescript dts file
+│ └── index.js # javascript entry file (esm)
├── content
│ ├── posts
│ │ ├── hello-world.md
│ │ └── other.md
│ └── others
│ └── other.yml
├── public
+│ └── static
+│ ├── cover-2a4138dh.jpg # from frontmatter reference
+│ ├── img-2hd8f3sd.jpg # from content reference
+│ ├── plain-37d62h1s.txt # from content reference
+│ └── video-72hhd9f.mp4 # from frontmatter reference
├── package.json
└── velite.config.js
TIP
If you're using Git for version control, we recommend ignoring the .velite
directory by adding .velite
to your .gitignore
. This tells Git to ignore this directory and any files inside of it.
echo '\n.velite' >> .gitignore
If you have static files output, you also need to ignore the public/static
directory:
echo '\npublic/static' >> .gitignore
Run Velite with Watch Mode
Run velite dev
or velite
with --watch
option, then Velite will watch the contents files and rebuild them automatically when they are changed.
$ npx velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'
$ pnpm velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'
$ yarn velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'
$ bun velite dev
[VELITE] output entry file in '.velite' in 0.68ms
[VELITE] output 1 posts, 1 others in 0.47ms
[VELITE] output 2 assets in 1.38ms
[VELITE] build finished in 84.49ms
[VELITE] watching for changes in 'content'
For more information about define collections, see Define Collections.
Use Output in Your Project
Velite will generate a index.js
file in .velite
directory, you can import it in your project:
import { posts } from './.velite'
console.log(posts) // => [{ title: 'Hello world', slug: 'hello-world', ... }, ...]
TIP
Velite is Framework Agnostic, you can use it output with any framework or library you like.
For more information about using collections, see Using Collections.