(
The type of the component in the Vev. Can be standard, section,{' '}
action or both.
Default is standard.
),
],
[
{ name: 'size', type: 'object' },
() => (
<>
The default size of the component. Each dimension can be:
number — fixed px value
'auto' — auto size
{'{ value: number | \'auto\', autoOnly?: boolean, valueOnly?: boolean }'} — with constraints.
Use autoOnly to prevent the user from setting a fixed size, or valueOnly to prevent auto sizing.
Default is width: 100px and height: 100px.
),
],
[
{
name: 'props',
type: 'array',
},
() => (
<>
Array of Vev props
Vev props documentation
),
],
[
{
name: 'editableCSS',
type: 'array',
},
() => (
<>
Define CSS properties that will be editable in the Deisgn Editor.
Editable CSS documentation
),
],
[
{ name: 'component', type: 'ReactNode' },
'To render a custom component in the editing panel.',
],
[
{ name: 'panelType', type: 'string' },
() => (
<>
The type of the editing panel. Can be inline.
Default is not set (side panel).
),
],
[
{
name: 'children',
type: 'object',
},
() => (
name: string, icon: string;
To render Vev content as children.
Children documenation
),
],
[
{
name: 'interactions',
type: 'array',
},
() => (
<>
Array of Vev events
Interactions documentation
),
],
[
{
name: 'events',
type: 'array',
},
() => (
<>
Array of Vev events
Events documentation
),
],
]}
/>
### Examples
#### Simple (JavaScript)
The only required field is the `React component` and the field name.
```tsx title="my-component.js"
import React from 'react';
import { registerVevComponent } from '@vev/react';
const MyComponent = () => {
return Hello, Vev
;
};
registerVevComponent(MyComponent, {
name: 'My awesome component',
});
export default MyComponent;
```
#### Advanced (TypeScript)
A more complex example listing a set of products.
```tsx title="my-component.tsx"
import React from 'react';
import { registerVevComponent, Image } from '@vev/react';
import styles from './my-component.module.scss';
type Props = {
title: string;
image: {
src: string;
key: string;
};
products: {
title: string;
price: number;
image: {
src: string;
key: string;
};
}[];
};
const MyComponent = ({ title, image, products = [] }: Props) => {
return (
{title}
{products.map((product, i) => (
{product.title}
{product.price}
))}
);
};
registerVevComponent(MyComponent, {
name: 'My awesome component',
type: 'section',
props: [
{
name: 'title',
type: 'string',
},
{
name: 'image',
type: 'image',
},
{
name: 'products',
type: 'array',
of: [
{ name: 'name', type: 'string' },
{ name: 'price', type: 'number' },
{ name: 'image', type: 'image' },
],
},
],
editableCSS: [
{
selector: styles.wrapper,
properties: ['background-color'],
},
{
selector: styles.productBorder,
properties: ['border-color'],
},
],
});
export default MyComponent;
```
***
See [Recipes](/react/recipes) for practical examples using `registerVevComponent`.
import Table from '../../components/Table';
## Props
Props are properties sent from the [Design Editor](https://editor.vev.design/) to your component(s).
### Base
All props share these common properties:
(
<>
Type of the prop. Can be one of the following:
string | number | boolean | image | video | audio | color | icon | object | array |
select | link | upload | menu | layout | variable
.
),
],
[
{ name: 'title', type: 'string' },
'Title of the prop visible in the editor. If not set, a sentence case of the name will be used',
],
[{ name: 'description', type: 'string' }, 'Description of the prop visible in the editor.'],
[{ name: 'component', type: 'ReactNode' }, 'Replaces the field with a custom React component.'],
[
{
name: 'initialValue',
type: 'JSON',
},
() => (
<>
The initial value for the field. Have to match the type of the field. Can also be a
function or async function returning the value. Function takes one argument
with the type
context.
),
],
[
{
name: 'validate',
type: 'boolean | function',
},
() => (
<>
Can either be boolean or a function returning boolean. The first
argument of the function is the value of the field and the second is the{' '}
context of the entire form.
),
],
[
{
name: 'hidden',
type: 'boolean | function',
},
() => (
<>
Hide/show field. Can either be boolean or a function returning{' '}
boolean. The first argument of the function is the{' '}
context of the entire form. The second is the{' '}
index of the current array item, or undefined if the field is
not inside an array. Can be used to toggle visibility based on values from other fields,
e.g. {'hidden: (context, index) => !context.value.cards[index].showTitle'}.
),
],
[
{
name: 'onChange',
type: ' function',
},
() => (
<>
A custom onChange for the field. The first argument of the function is the{' '}
value of the field and the second is the{' '}
context of the entire form.
),
],
[
{ name: 'storage', type: 'string' },
() => (
<>
Select where to store values for the component (like API keys etc.). Can be{' '}
project | workspace | account.{' '}
),
],
[
{ name: 'flex', type: 'boolean' },
'When true, the field stretches to fill available space inside a row layout.',
],
]}
/>
### String
A field type for string.
```ts
type: "string",
```
Options:
(
<>
Can be 'text' | 'date' | 'email' | 'url' | 'password'. Default is{' '}
text.
),
],
[
{ name: 'multiline', type: 'boolean | number' },
() => (
<>
Select if the field should be multiline or not. Can either be boolean or a{' '}
number representing the lines of the text the field should include.
),
],
[{ name: 'placeholder', type: 'string' }, 'Placeholder text shown when the field is empty.'],
[{ name: 'minLength', type: 'number' }, () => <>The minimum characters for the field.],
[{ name: 'maxLength', type: 'number' }, () => <>The maximum characters for the field.],
[
{ name: 'html', type: 'boolean' },
'When true, displays a rich text editor with formatting toolbar (bold, italic, underline, headings, lists, links, etc.). The stored value is an HTML string.',
],
]}
/>
**Example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'title',
type: 'string',
options: {
multiline: 3,
placeholder: 'Enter a title...',
},
},
],
});
```
**Rich text example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'description',
type: 'string',
options: {
html: true,
},
},
],
});
```
*See recipe: [Hello World](/react/recipes#hello-world)*
### Number
A field type for number.
```ts
type: "number",
```
(
<>
The appearance of the field. Can be 'input' | 'slider' | 'range-slider'.
Default is: input. The range-slider displays a dual-handle slider
and stores a [min, max] tuple.
),
],
[
{ name: 'formats', type: 'string[]' },
() => (
<>
Allowed unit formats for the number input (e.g. ["px", "%", "em", "None"]).
Defaults to ["None"] (plain number). When a format other than None{' '}
is selected, the stored value includes the unit suffix (e.g. "20px").
),
],
[
{ name: 'precision', type: 'number' },
'Number of decimal places. Overrides the default precision for the format. When format is None, defaults to 0 (integers).',
],
[{ name: 'placeholder', type: 'string' }, 'Placeholder text shown when the field is empty.'],
]}
/>
**Example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
// Simple number input (stores integer)
{ name: 'count', type: 'number' },
// Slider with scaling: stores 0–1, displays 0–100%
{
name: 'opacity',
type: 'number',
options: { min: 0, max: 100, scale: 100, display: 'slider' },
},
// Range slider: stores [min, max] tuple
{
name: 'priceRange',
type: 'number',
options: { min: 0, max: 1000, display: 'range-slider' },
},
// Number with units
{
name: 'width',
type: 'number',
options: { formats: ['px', '%', 'em'] },
},
// Decimal precision
{
name: 'ratio',
type: 'number',
options: { precision: 2 },
},
],
});
```
### Boolean
A field type for boolean. Displays a toggle switch by default, or a checkbox.
```ts
type: "boolean",
```
(
<>
Can be 'toggle' | 'checkbox'. Default is toggle.
),
],
]}
/>
**Example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{ name: 'showOnMobile', type: 'boolean' },
{ name: 'acceptTerms', type: 'boolean', options: { display: 'checkbox' } },
],
});
```
*See recipe: [Conditional rendering](/react/recipes#conditional-rendering)*
### Select
Can be used to display either radio buttons, a dropdown, checkbox list, or autocomplete.
```ts
type: "select",
```
Options:
(
<>
An array of options in this format: label: string, value: string.
Can also be async.
),
],
[
{ name: 'display', type: 'string' },
() => (
<>
{' '}
Can be: 'checkbox' | 'radio' | 'dropdown' | 'autocomplete'.
Default is dropdown.
),
],
[
{ name: 'multiselect', type: 'boolean' },
'If it should be possible to select multiple values.',
],
[{ name: 'placeholder', type: 'string' }, 'Placeholder text when nothing is selected.'],
]}
/>
**Example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'selectFruits',
type: 'select',
options: {
display: 'radio',
items: [
{ label: 'Apple', value: 'apple' },
{ label: 'Orange', value: 'orange' },
{ label: 'Banana', value: 'banana' },
],
},
},
],
});
```
*See recipe: [Select](/react/recipes#select)*
### Image
A field type for `image`. This will display an image upload field in the editor.
```ts
type: "image",
```
**Example:**
```js
import { Image } from '@vev/react';
function MyComponent({ image }) {
return ;
}
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'image',
type: 'image',
title: 'Image',
},
],
});
```
The `Image` component from `@vev/react` accepts a `src` prop with the image value. It handles responsive images and optimized loading automatically.
*See recipe: [Image with caption](/react/recipes#image-with-caption)*
### Video
A field type for `video`. This will display a video upload field in the editor.
```ts
type: "video",
```
**Example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'video',
type: 'video',
},
],
});
```
### Audio
A field type for `audio`. This will display an audio upload field in the editor.
```ts
type: "audio",
```
**Example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'audio',
type: 'audio',
},
],
});
```
### Color
A field type for `color`. This will display a color picker in the editor. The stored value is a color string (hex, rgba, etc.).
```ts
type: "color",
```
**Example:**
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'backgroundColor',
type: 'color',
},
],
});
```
*See recipe: [Editable CSS](/react/recipes#editable-css)*
### Icon
A field type for `icon`. This will display an icon/shape picker in the editor. Stores the full shape object `{ key, name, path }` where `path` is `[width, height, pathData]`.
```ts
type: "icon",
```
**Example:**
```js
import { Icon } from '@vev/react';
function MyComponent({ icon }) {
return ;
}
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'icon',
type: 'icon',
title: 'Icon',
},
],
});
```
The `Icon` component from `@vev/react` accepts a `d` prop with the icon value. It handles SVG shapes, legacy path arrays, and image URLs automatically.
### Link
A field for `link`. This will display a link field in the editor.
This will give a search field for internal links. If an internal link
is not selected it will behave like an external link.
```ts
type: "link",
```
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'link',
type: 'link',
},
],
});
```
### Object
A field type for `object`. This can be used to display fields in a group.
All the Vev props can be used as `fields`.
```ts
type: "object",
fields: VevProps[],
```
##### Example
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'header',
type: 'object',
fields: [
{
name: 'title',
type: 'string',
},
{ name: 'subtitle', type: 'string' },
{ name: 'image', type: 'image' },
],
},
],
});
```
### Array
A field type for `array`. The `of` property defines which item types are available when adding to the list.
##### Simple arrays
For arrays of a single primitive type, set `of` to `'string'` or `'number'`:
```js
{
name: 'tags',
type: 'array',
of: 'string',
}
```
##### Array of objects with fields
Set `of` to `'object'` and provide `fields` directly on the array field:
```js
{
name: 'links',
type: 'array',
of: 'object',
fields: [
{ name: 'label', type: 'string' },
{ name: 'url', type: 'string', options: { type: 'url' } },
{ name: 'external', type: 'boolean' },
],
}
```
##### Mixed arrays
When `of` contains multiple entries, the editor shows a dropdown when adding an item so the user can choose the type:
```js
{
name: 'content',
type: 'array',
of: [
{
name: 'text',
type: 'object',
title: 'Text Block',
fields: [
{ name: 'heading', type: 'string' },
{ name: 'body', type: 'string', options: { multiline: 3 } },
],
},
{
name: 'image',
type: 'object',
title: 'Image Block',
fields: [
{ name: 'src', type: 'image' },
{ name: 'alt', type: 'string' },
],
},
],
}
```
##### List preview
Every element in an array field can have a custom list preview. If not defined, the editor will try to find a title and image from the data.
(
<>
can either be an object or a function which returns an object:{' '}
title: string, image: string.
),
],
]}
/>
##### Example
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'products',
type: 'array',
of: 'object',
fields: [
{ name: 'title', type: 'string' },
{ name: 'price', type: 'number' },
{ name: 'image', type: 'image' },
],
preview(value) {
return {
title: value.title,
image: value.image?.url,
};
},
},
],
});
```
*See recipe: [Card list](/react/recipes#card-list)*
### Layout containers
Container field types organize the form UI without creating properties in the form value.
#### Layout row
Arranges child fields in a row or column. Use `flex: true` on fields that should stretch to fill available space.
```js
{
type: 'layout',
options: { display: 'row' },
fields: [
{ name: 'x', type: 'number', title: 'X', flex: true },
{ name: 'y', type: 'number', title: 'Y', flex: true },
],
}
```
Options:
(
<>
Can be row | column. Default is row.
),
],
]}
/>
#### Group
A collapsible card section. Set `collapsed: true` in options to start closed.
```js
{
type: 'group',
title: 'Advanced Settings',
options: { collapsed: true },
fields: [
{ name: 'zIndex', type: 'number' },
{ name: 'cssClass', type: 'string' },
],
}
```
#### Popover
An icon button that opens a popover with nested fields. Useful for tucking away secondary settings.
```js
{
type: 'popover',
title: 'Spacing',
options: { icon: 'settings' },
fields: [
{ name: 'padTop', type: 'number', title: 'Top' },
{ name: 'padBottom', type: 'number', title: 'Bottom' },
],
}
```
#### Divider
A horizontal line to visually separate groups of fields.
```js
{ type: 'divider' }
```
### Full layout example
```js
registerVevComponent(MyComponent, {
name: 'Hero Section',
props: [
{ name: 'heading', type: 'string', initialValue: 'Welcome' },
{ name: 'body', type: 'string', options: { multiline: 3 } },
{ type: 'divider' },
{
type: 'group',
title: 'Layout',
fields: [
{
type: 'layout', options: { display: 'row' },
fields: [
{ name: 'columns', type: 'number', title: 'Cols', flex: true },
{ name: 'gap', type: 'number', title: 'Gap', flex: true },
],
},
{
type: 'layout', options: { display: 'row' },
fields: [
{ name: 'align', type: 'select', title: 'Align', flex: true, options: {
display: 'dropdown',
items: [
{ label: 'Left', value: 'left' },
{ label: 'Center', value: 'center' },
{ label: 'Right', value: 'right' },
],
}},
{
type: 'popover',
title: 'Spacing',
options: { icon: 'settings' },
fields: [
{ name: 'padTop', type: 'number', title: 'Top' },
{ name: 'padBottom', type: 'number', title: 'Bottom' },
],
},
],
},
],
},
{
type: 'group',
title: 'Advanced',
options: { collapsed: true },
fields: [
{ name: 'lazyLoad', type: 'boolean' },
{ name: 'anchor', type: 'string', title: 'Anchor ID' },
],
},
],
});
```
### Upload
A field to be used for uploading files.
```ts
type: "upload",
fields: VevProps[],
```
Options:
(
<>
A comma separated list of{' '}
unique file type specifiers
.
),
],
]}
/>
##### Example
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
type: 'upload',
accept: '.jpg,.png',
},
],
});
```
### Menu
A field for adding/editing project menus. Use in conjunction with [useMenu](/react/hooks#usemenu).
```ts
type: "menu",
```
##### Example
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'projectMenu',
type: 'menu',
},
],
});
```
### Variable
A field used for getting variable keys. Use in conjunction with [useVariable](/react/hooks#usevariable) and [useSetVariable](/react/hooks#usesetvariable).
```ts
type: "variable",
```
Options:
(
<>
Filter variables by type. Can be 'color' | 'number' | 'font' | 'text'.
),
],
]}
/>
##### Example
```js
registerVevComponent(MyComponent, {
name: 'My component',
props: [
{
name: 'variableKey',
type: 'variable',
},
],
});
```
***
See [Recipes](/react/recipes) for practical examples using props.
## Types
### Context
Argument for functions initialValue
and hidden in [Vev props](/react/vev-props)
```ts
export type SchemaContextModel = {
key?: string;
value?: Partial;
storage?: SchemaStorage;
/**
* Project
*/
project?: { title: string; key: string; index: string };
/**
* Project pages
*/
pages?: { title: string; key: string; path?: string }[];
currentPage?: { title: string; key: string; path?: string; project?: string };
/**
* Named content models
*/
content?: {
key: string;
name?: string;
parentKey: string;
type: string;
content?: { [key: string]: any };
}[];
/**
* Events
*/
events?: VevContentEvent[];
};
```
## Client Rendering
For client-side rendering, we use the [Vev Embed](https://help.vev.design/en/articles/6141975-embed-your-project).
Vev Embed provides a super lightweight and fast way to render a Vev project on the client side.
#### Vev Embed
The Vev Embed is a optimized way to render a project client side. The embed will insert HTML synchronous, and then defer the hydration until HTML is fully rendered [hydrate](https://18.react.dev/reference/react-dom/client/hydrateRoot) the project. If blocking render is not desired, you can add asyn to the script tag to prevent this
* **Variable Replacement:** Supports the dynamic replacement of any Vev variable directly in the browser.
* **Performance Optimized:** Designed to be lightweight and fast, ensuring minimal impact on page load times.
### Example
This is a [Vev example project](https://editor.vev.design/edit/U1TM1EJXg9/pv5RwtffJq7), built using variables.
* **Project Overview:** This project demonstrates how variables are utilized to create dynamic content.
* **Dynamic Updates:** Variables in this project can be updated dynamically, showcasing client-side rendering in action.
```js
```
#### Codesandbox
This is a live working example.
## How to Connect to a CMS
[Vev](https://editor.vev.design/) is a powerful front-end editor designed to seamlessly integrate with any CMS (Content Management System) or other data sources, enabling dynamic content display. It supports both [client side](/cms/client-side) and [server side](/cms/server-side) rendering, making it adaptable to any web application built with any programming language or framework.
With Vev, you can build a fully customizable frontend that can be entirely self-hosted alongside your existing frontend architecture. Either to build full pages or components. It can also be used alongside existing content.
### Variables
Variables are the backbone of dynamic projects in Vev, enabling external modification of content.
[Variables](https://help.vev.design/en/articles/9674244-setting-up-and-managing-variables) are placeholders in your Vev project that dynamically update with data from a CMS or other sources. Here's how to get started:
* Identify the elements in your project (e.g., text, images, styling) that will use variables.
* Configure these elements to accept dynamic data.
**Supported variables:**
* **Text Variables:** Dynamically update text, such as titles or descriptions.
* **Image Variables:** Swap or update images without modifying the project manually.
* **List Variables:** Perfect for collections, like slider or list items.
* **Styling Variables:** Modify styles dynamically, such as colors or sizes.
### Compile project
The [Vev CLI](/cli/getting-started) allows you to [compile](/cli/commands#compile) your project into static files for seamless integration with any CMS and web application.
The compiled files also include an `embed/[pageKey].js` script, for client side rendering script, and `template/[pageKey].mustache` file for serer side rendering.
To compile the project, you run the the [compile command](/cli/commands#compile):
```bash
vev compile [project-id]
```
:::info
You can also specify the project to compile in [vev.json](/cli/commands#compile).
:::
* **Benefits of Compiling:**
* Converts Vev projects into deployable files (HTML, CSS, JavaScript).
* Facilitates efficient storage and integration with CMS data.
* **Storage Tip:** Store the compiled files in your web application's static folder for optimal performance.
### Replace variables
Vev provides two primary methods for variable replacement:
#### Client Rendering
* **How it Works:** Variables are replaced in the browser after the page loads using Vev Embed.
* **Best For:** Scenarios where you do not have a server available.
[Documentation for client rendering](/cms/client-side)
#### Server Rendering
* **How it Works:** Variables are replaced on the server using Mustache templates.
* **Best For:** Scenarios where you have server.
By following these steps and leveraging Vev's flexibility, you can create dynamic, efficient, and highly customizable front-end projects that seamlessly connect to any CMS or data source.
[Documentation for server rendering](/cms/client-side)
## Server rendering
For server rendering, Vev is using [Mustache](https://mustache.github.io/), which is a generic templating language which can be used with a wide range of programming languages like PHP, Java, .NET and JavaScript.
### Example implementations
This is a [Vev example project](https://editor.vev.design/edit/U1TM1EJXg9/pv5RwtffJq7), built using variables.
#### NodeJS
```js
import Mustache from 'mustache';
import fs from 'fs/promises';
const template = await fs.readFile('/template/p8S9MxkirVE.mustache', 'utf8');
const renderedHTML = Mustache.render(template, {
// primary
'c--hWX11RLvP': '#000 | rgba(0,0,0,0.5) | hsl(0,0%,0%) | hsla(0,0%,0%,0.5)',
// Hero image
'i-JZiYWYXa7J': {
src: 'https://img.url',
alt: 'Image alt text',
srcset: 'https://img.url 300w, https://img.url 600w, https://img.url 900w',
},
// Hero title
't-4RyfGtGYj2': 'Text',
// Hero CTA url
't-8ec2OwGaF_': 'Text',
// Hero CTA text
't-DzxChO2qSm': 'Text',
// Hero subtitle
't-hd1jsFgPV5': 'Text',
});
res.send(renderedHTML);
```
#### PHP
```php
new Mustache_Loader_FilesystemLoader('/template') // Set the template directory
]);
// Read the Mustache template file
$templateFile = 'p8S9MxkirVE.mustache';
$template = file_get_contents(__DIR__ . "/template/" . $templateFile);
// Define data for the template
$data = [
// primary
'c--hWX11RLvP' => "#000 | rgba(0,0,0,0.5) | hsl(0,0%,0%) | hsla(0,0%,0%,0.5)",
// Hero image
'i-JZiYWYXa7J' => [
"src" => "https://img.url",
"alt" => "Image alt text",
"srcset" => "https://img.url 300w, https://img.url 600w, https://img.url 900w"
],
// Hero title
't-4RyfGtGYj2' => "Text",
// Hero CTA url
't-8ec2OwGaF_' => "Text",
// Hero CTA text
't-DzxChO2qSm' => "Text",
// Hero subtitle
't-hd1jsFgPV5' => "Text",
];
// Render the template
$renderedHTML = $mustache->render($template, $data);
// Send the response
header('Content-Type: text/html');
echo $renderedHTML;
?>
```
#### Go
```go
package main
import (
"io/ioutil"
"log"
"net/http"
"github.com/hoisie/mustache"
)
func handler(w http.ResponseWriter, r *http.Request) {
// Read the Mustache template file
template, err := ioutil.ReadFile("/template/p8S9MxkirVE.mustache")
if err != nil {
log.Fatalf("Error reading template file: %v", err)
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
return
}
// Define the data to pass into the template
data := map[string]interface{}{
"c--hWX11RLvP": "#000 | rgba(0,0,0,0.5) | hsl(0,0%,0%) | hsla(0,0%,0%,0.5)",
"i-JZiYWYXa7J": map[string]string{
"src": "https://img.url",
"alt": "Image alt text",
"srcset": "https://img.url 300w, https://img.url 600w, https://img.url 900w",
},
"t-4RyfGtGYj2": "Text",
"t-8ec2OwGaF_": "Text",
"t-DzxChO2qSm": "Text",
"t-hd1jsFgPV5": "Text",
}
// Render the template with the data
renderedHTML := mustache.Render(string(template), data)
// Write the rendered HTML to the response
w.Header().Set("Content-Type", "text/html")
_, err = w.Write([]byte(renderedHTML))
if err != nil {
log.Printf("Error writing response: %v", err)
}
}
func main() {
http.HandleFunc("/", handler)
log.Println("Server is running on port 8080...")
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
## Getting started
How to get started with [Vev](https://vev.design) using the command-line interface (CLI), and local development of
custom [React components](https://reactjs.org/) in Vev.
:::warning
You need [Node.js](https://nodejs.org/) **v22 or higher** to run the Vev CLI.
:::
#### Install CLI
First you need to install the CLI from NPM (or Yarn).
```js
npm install -g @vev/cli
```
* [Available CLI commands](/cli/commands)
#### Authorize the CLI
After that you need a [Vev account](https://editor.vev.design), and then authorize the CLI:
```js
vev login
```
#### Bootstrap your project
It is not needed to add your components to a specific Vev project, it can be determined later if you want your component
to be available for only a specific project or for a whole account.
To create a new project:
```bash
vev create [my-project]
```
You can also use the CLI in an existing React project. Then you just need to add
the [@vev/react](https://www.npmjs.com/package/@vev/react) package.
In your project directory run:
```bash
cd [my-project]
vev init
```
### Create your first component
The `registerVevComponent` function can be used everywhere inside a `./src` directory. But all components needs to be
exported.
```ts title="my-component.js"
import React from 'react';
import { registerVevComponent } from '@vev/react';
const MyComponent = () => {
return Hello, VeV
;
}
registerVevComponent(MyComponent, {
name: "My awesome component",
});
export default MyComponent;
```
Further reads:
* [Register component](/react/register-vev-component)
* [Vev props](/react/vev-props)
* [Vev components](/react/components)
* [Vev hooks](/react/hooks)
* [Recipes](/react/recipes)
### Run you components
Now you are ready to run your components in the Vev Editor.
```
vev start
```
Now you can open the [Vev design editor](https://editor.vev.design/) and your components will be available in all your
projects as long as the CLI is running.
## Web workers
:::info
Web Workers allow you to run scripts in background threads, preventing heavy computations from blocking the main thread or interfering with rendering.
[Learn more about Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
:::
Vev provides full support for Web Workers in CLI components.
You can import a Web Worker script directly by appending ?worker to your import path. The default export will be a worker constructor:
```tsx
import Worker from './my-worker?worker';
const myWorker = new Worker();
```
Inside the worker, you can use standard ES module imports — no need for [importScripts](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts).
### Example
A common use case for Web Workers in Vev is to preload and process multiple images in the background — for example, when building a video scroll component that uses images instead of an actual video file.
```ts filename="example.ts"
import { useEffect, useRef } from "react";
import ImageWorker from "./image-load-worker?worker"; // [!code focus]
export function useVideoImageWorker(images: string[]) {
const imagesRef = useRef([]);
useEffect(() => {
const worker = new ImageWorker(); // [!code focus]
worker.addEventListener('message', async (e: any) => {
const { url, index } = e.data as { index: number; url: string };
const img = await resolveImage(url);
const images = imagesRef.current;
if (images && img) images[index] = img;
});
worker.postMessage({ // [!code focus]
images, // [!code focus]
parentLocation: `${self.location.origin}${self.location.pathname}`, // [!code focus]
}); // [!code focus]
return () => worker.terminate(); // [!code focus]
}, [images]);
return imagesRef;
}
```
In this setup, the worker handles loading and caching of image sequences efficiently, allowing smooth scrubbing and playback on scroll without blocking the main UI thread.
[Full code for Video Scroll component](https://github.com/vev-design/vev-components/blob/main/video-scroll/)
## Commands
:::warning
You will first need a Vev user, [sign up here](https://editor.vev.design/signup).
:::
You also need [Node.js](https://nodejs.org/) **v22 or higher** installed.
To install the CLI:
```
npm i @vev/cli -g
```
### login
To authorize the CLI against the [Design Editor](https://editor.vev.design):
```bash
vev login
```
This will authorize the CLI against Vev, and save an access token to your computer which will be used for further requests. You need to login before you can start initializing packages.
To force a new login or log in to another account use:
```bash
vev login --force
```
### create
To get started easily and get a boiler of React and TypeScript setup.
```bash
vev create [my-project]
```
Based on this [boilerplate](https://github.com/vev-design/create-vev-app).
This is not required to use the CLI, you can also use your own setup and add the [@vev/react](/react/register-vev-component) package manually.
### initialize
To start working on Vev components, you need to run initialize first.
```bash
vev init
```
This will create a new component package in Vev that later can be deployed. In your local files, a new `vev.json` file will be created containing your component `key`. Never delete this file, while this will detach your component from Vev, if you do so you will have to initialize a new component package.
:::caution
Never delete the **vev.json** file.
:::
This command will also create a `.vev` folder containing all of your local builds. This folder can be deleted at any point and will be automatically recreated when needed. This folder does not need to be checked into source control.
### start
To view your components the [Design Editor](https://editor.vev.design).
```bash
vev start
```
Now you can open the [Design Editor](https://editor.vev.design) and open any project. Now you will see a green dot in the bottom of the editor. This means your local machine is connected with Vev. Clicking the dot will give you a menu where you can start using the components inside the [Design Editor](https://editor.vev.design).
To show more messages and debug messages to `stdout`, you can add the `--debug` flag to your start command.
```bash
vev start --debug
```
### deploy
```bash
vev deploy
```
This will deploy the component and make it available in the [Design Editor](https://editor.vev.design).
Available options can be set in [vev.json](/cli/configuration).
This will create *one* optimized JavaScript and CSS bundle which will be shared among all widgets within the package.
For optimization, make separate packages if your widgets does not shared common code, using *Context* (or other global shared logic). This will create more optimal bundles.
import Table from '../../components/Table';
## Configuration
To configure your component package use the `vev.json` file. This file will contain the `key` for the component which connects your component package to Vev.
:::danger
Never delete the **vev.json** file.
:::
### Options
(
<>
They key is auto generated when running vev init and should
never been changed.
),
],
[
{
name: 'shareWithAccount',
type: 'boolean',
},
'Option to make the component available in the add menu for everyone on your account after deployed.',
],
[
{
name: 'library',
type: 'object',
},
() => (
<>
Object containing key, which is the Vev project key, and dist{' '}
(optional) to specify the destination folder for the compiled files.
),
],
]}
/>
## Tailwind
The Vev CLI natively supports [Tailwind CSS](https://tailwindcss.com/docs/installation), requiring minimal setup. Simply add a Tailwind configuration file to the root of your project.
No extra configuration is necessary, as the `tailwindcss` package is already included.
```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ['src/**/*.{ts,tsx}'],
corePlugins: {
preflight: false,
},
};
```
:::info
[Tailwind](https://tailwindcss.com/docs/installation) is a utility-first framework that allows you to design directly in your HTML using predefined classes, without needing to write custom CSS. It’s ideal for building responsive, custom designs quickly.
:::
### Disabling preflight
We recommend disabling [Tailwind's Preflight](https://tailwindcss.com/docs/preflight#disabling-preflight), as it can conflict with Vev’s built-in reset styles, potentially causing issues with how styles are applied.
You can customize the configuration, add plugins, and include additional packages as you normally would with Tailwind.
## Using Secrets
### Plugin form
If you need to use credentials or other secrets like an API-key to connect to your asset repository use the `form` part
of `registerVevComponent`:
```typescript
registerVevPlugin({
form: [
{
type: "string",
name: "API_KEY",
title: "API Key",
},
],
...
});
```
The type of the form is described [here](/react/vev-props)
This form will show up when connecting the asset source and will deploy together with the serverless function, meaning it's not retrievable by anyone:
### Retrieving secrets
The values will then be available on the `env` object in the handler function:
```typescript
async function handler(
env: Record,
...
): Promise {
const apiKeyFromForm = env.API_KEY;
...
```
## Asset Source
An asset source is handled by the plugins system. You can add a plugin to extend Vev assets library and connect a DAM or other asset sources.
### Create a new plugin
To create an asset source plugin first clone [this](https://github.com/vev-design/editor-plugins/tree/main/asset-source-template) template project.
Change the name to something appropriate for your plugin and assign a unique ID (this can be anything, but it must be unique to your account):
```javascript
registerVevPlugin({
name: "Your plugin name",
id: '[your-id]',
...
});
```
In your project directory run:
```bash
cd [my-project]
vev init
```
and after this is successful:
```bash
vev deploy
```
### Connecting a plugin
To connect and start using your plugin go to [editor plugins](https://editor.vev.design/account/editor-plugin#) in account settings.
You should now see your new plugin in the list and be able to connect it:
After connecting the plugin you should now be able to see the results in the Vev design editor:
### Logs and debugging
To see the logs of your asset source after you have connected it go to [editor plugins](https://editor.vev.design/account/editor-plugin#) in account settings.
In the dropdown to the right there is an option to open the log viewer:
### Further reading
* To learn more about the handler function and supported return types, visit [this page](/asset-source/handler-function).
* For information on handling secrets, such as API keys and other credentials, go [here](/asset-source/api-keys).
* To understand how to add configurable settings to your plugin, refer to \[this guide].
* For details on adding filtering or advanced search features in the Vev editor, check out \[this resource].
## Handler function
The handler function retrieves information about your assets and return them in a format the Vev editor understands.
The handler function returns an array of image or video assets.
```typescript
registerVevPlugin({
handler: () => {...},
...
});
```
### Asset types
#### Base asset
All asset types extends the base asset type:
```typescript
export interface BaseProjectAsset {
key: string; // A unique id for the asset
mimeType: string; // The mime type of the asset (image/jpeg, video/mp4 etc.)
url: string; // The url where the Vev editor can reach the asset
filename?: string; // Optional filename
selfHosted?: boolean; // If you want to host your own asset make sure this is true
}
```
#### Image assets
```typescript
export interface ProjectImageAsset extends BaseProjectAsset {
dimension?: { width: number; height: number };
thumb?: string; // A thumbnail for faster loading in the Vev editor
imageSizes?: ImageSizes; // A set of custom image sizes if you are hosting your own assets
}
```
#### Video assets
```typescript
export interface ProjectVideoAsset extends BaseProjectAsset {
videoSample?: string; // A smaller video sample for faster loading in the Vev editor
videoThumbnail?: string; // A thumbnail for faster loading in the Vev editor
dimension?: { width: number; height: number };
duration?: number; // The duration of the video on seconds
additionalSources: Omit[]; // Additional sources/formats if you are hosting your own assets
}
```
## Custom Asset Sources
Custom asset sources enable you to integrate videos, images, and other media assets from your CMS, [Digital Asset Management (DAM)](https://en.wikipedia.org/wiki/Digital_asset_management)
systems, or other media repositories into the Vev editor.
The asset sources are deployed in their own isolated environment, meaning any secrets or credentials are
not readable by anyone.
To create a custom asset source, you need to install the Vev [CLI](/cli/getting-started).
For additional information, begin with our [Getting Started guide](getting-started) or explore our [repository](https://github.com/vev-design/editor-plugins) for more advanced example implementations.
:::info
User-made asset sources are in beta. Contact support to get access to deploying your custom asset sources.
:::
:::info
Asset source functions do not run in a Node.js environment, so any libraries with dependencies specific to Node.js will not work.
:::
## Authorization
To authorize, you need to create a token.
### Create API key
In the [Design Editor](https://editor.vev.design), go to [user profile](https://editor.vev.design/user) and create a API key, with the relevant scope.
The API key will be valid forever until it is revoked.
### Authorized request
Test your newly created token:
```bash
curl --header "x-vev-key: [your-key]" https://api.vev.design/api-key/introspection
```
To make authorized requests, you need to add the `x-vev-key` header to every request.
import ScalarApiReference from '../../components/ScalarApiReference';