https://github.com/directus/visual-editing-test-website
Template data for the @directus/visual-editing test website, applied via directus-template-cli
https://github.com/directus/visual-editing-test-website
cms directus directus-template headless-cms nuxt template testing visual-editing
Last synced: about 11 hours ago
JSON representation
Template data for the @directus/visual-editing test website, applied via directus-template-cli
- Host: GitHub
- URL: https://github.com/directus/visual-editing-test-website
- Owner: directus
- License: other
- Created: 2026-04-22T17:33:13.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-19T16:26:05.000Z (about 2 months ago)
- Last Synced: 2026-05-27T21:30:31.046Z (about 1 month ago)
- Topics: cms, directus, directus-template, headless-cms, nuxt, template, testing, visual-editing
- Language: Vue
- Homepage: https://github.com/directus/directus/tree/main/packages/visual-editing/test-website/readme.md
- Size: 13.4 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: license
Awesome Lists containing this project
README
# Visual Editing Test Website
> [!NOTE]
>
> The following test website and guide are intended to be used for testing and development purposes, not for production
> use!
## Setup Instructions
While you can also set up the Visual Editing test website with a Directus instance running in a
[Docker](https://directus.io/docs/getting-started/create-a-project#docker-installation) container, this guide describes
setting up a development environment using the official Directus repository.
### Set up your Directus Dev Instance
1. Clone the official [Directus GitHub repository](https://github.com/directus/directus), make sure you have the
dependencies installed (`pnpm i`) and build everything (`pnpm build`)!
2. Create a new database (sqlite is recommended for development) and add the env config in `api/.env`
Example .env file
```sh
PUBLIC_URL=http://localhost:8080
KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
ADMIN_EMAIL=admin@directus.io
ADMIN_PASSWORD=secret
CACHE_ENABLED=true
CACHE_AUTO_PURGE=true
CACHE_TTL=1d
CORS_ENABLED=true
CORS_ORIGIN=http://localhost:3000
CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC=http://localhost:3000
DB_CLIENT=sqlite3
DB_FILENAME=db.sqlite3
```
3. Double check that the following env vars are set:
```sh
CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC=http://localhost:3000
CACHE_AUTO_PURGE=true
```
4. Run `pnpm --filter api cli bootstrap` to set up the db
5. Run the dev servers: `pnpm --filter api dev` and `pnpm --filter app dev`
6. Login to Directus Studio, create a token for your user and have it ready
### Set up the test website
1. Clone this repository, open it in a new window in your code editor on the `main` branch
2. Install dependencies: `pnpm i`
3. Add the env vars to `.env` and make sure to provide `` and the correct `DIRECTUS_URL`.
```sh
DIRECTUS_URL=http://localhost:8080
DIRECTUS_FORM_TOKEN=
DIRECTUS_SERVER_TOKEN=
NUXT_PUBLIC_SITE_URL=http://localhost:3000
```
4. Now, install the Directus template.
```sh
cd template && npm run setup-directus
```
On Windows, apply the Directus template with the
[directus-template-cli](https://www.npmjs.com/package/directus-template-cli) to populate your instance with the
required schema and content. Run this from the repo root and make sure to replace `` with your Directus
URL and `` with the token you generated earlier.
```sh
npx directus-template-cli@latest apply -p --templateLocation=./template --templateType=local --directusUrl= --directusToken=
```
### Run the test website
Run the test website with `pnpm visual-editing:ssr--refresh`.
> [!NOTE]
>
> See the description of the different “Test Modes” below
### Develop against a local `@directus/visual-editing` source
By default, `pnpm i` pulls the latest published `@directus/visual-editing` from npm and it is consumed from
`node_modules` as installed. To test against your local working copy inside the `directus/directus` monorepo, set
`DIRECTUS_LOCAL_PATH` in `.env` to point to your monorepo checkout:
```sh
DIRECTUS_LOCAL_PATH=../directus
```
When set, Vite aliases `@directus/visual-editing` directly to the package source
(`packages/visual-editing/src/index.ts`) — no build step is required in the monorepo, edits are picked up on dev-server
reload. Unset (or comment out) the var to fall back to the installed npm package in `node_modules`.
> [!NOTE]
>
> The `monolith` test mode serves `visual-editing.js` via a plain `` tag, so it needs a pre-bundled file. When
> `DIRECTUS_LOCAL_PATH` is set, the build copies from
> `<DIRECTUS_LOCAL_PATH>/packages/visual-editing/dist/visual-editing.js` instead of `node_modules`, so a build step in
> the monorepo (`pnpm --filter visual-editing build`) is still required before running `pnpm visual-editing:monolith`.
### Set up Directus Visual Editor module
1. Switch to Directus Studio
2. Enable the Visual Editor module in settings
3. Add the following URL to the Visual Editor settings (on the settings page)
- `http://localhost:3000?version={{$version}}`
4. Open the Visual Editor Module
## Test Modes
Use the following commands to run predefined test environments. Find the corresponding code by searching for
`useVisualEditingTest` or `testCase` in the test-website directory to see how it is set up.
> [!NOTE]
>
> Be sure to stop other servers running on localhost:3000
```sh
# commands
pnpm visual-editing:monolith
pnpm visual-editing:ssr
pnpm visual-editing:ssr--refresh-all
pnpm visual-editing:ssr--refresh
pnpm visual-editing:ssr--refresh-customized # http://localhost:3000/blog
pnpm visual-editing:ssr--methods # http://localhost:3000
pnpm visual-editing:dev
pnpm visual-editing:dev--refresh-all
pnpm visual-editing:dev--refresh
pnpm visual-editing:dev--refresh-customized # http://localhost:3000/blog
pnpm visual-editing:dev--methods # http://localhost:3000
pnpm visual-editing:ssg # http://localhost:3000/blog/why-steampunk-rabbits-are-the-future-of-work
```
### Rendering modes:
- Monolith / server only rendering: use as with PHP
- SSG: live data only on hydration
- SSR: always with live data
- Dev mode: if you want to play around
### Test Cases
- `basic`
- No `onSaved` callback — the web page inside the iframe will be reloaded (`window.location.reload()`)
- Editable elements are added and removed globally on route change
- Rendering modes: `monolith` || `dev` || `ssr`
- Search for `testCase === 'basic'`
- `refresh-all`
- `onSaved` will refetch all data with `refreshNuxtData()`
- Editable elements will be added and removed globally on route changes
- Rendering modes: `dev` || `ssr`
- Search for `testCase === 'refresh-all'`
- `refresh` _(smooth, recommended)_
- `onSaved` will call refetch all data where it was originally fetched.
- Editable elements are only removed globally on route changes, they are added in nested components where data is
fetched, so that their `refresh()` function can be passed to `onSaved`. This should provide the smoothest experience
without layout shifts.
- Rendering modes: `dev` || `ssr`
- Search for `testCase === 'refresh'`
- `refresh-customized`
- The best way to see this on the test website is to open this page in the Visual Editor: http://localhost:3000/blog
- Exactly the same as `refresh` above, except that custom classes are attached to some editable elements to
demonstrate customizability.
- Rendering modes: `dev` || `ssr`
- Search for `testCase === 'refresh-customized'`
- `methods`
- The best way to see this on the test website is to open this page in the Visual Editor: http://localhost:3000
- Exactly the same as `basic` above, except that there are buttons to test some useful functions/methods
- Rendering modes: `dev` || `ssr`
- Search for `testCase === 'methods'`
- `refresh-ssg`
- The best way to see this on the test website is to open this page in the Visual Editor:
http://localhost:3000/blog/why-steampunk-rabbits-are-the-future-of-work
- Exactly the same as `refresh` above, except that it is only available for SSG and on a blog page `/blog/[slug]`
- Rendering modes: `ssg`
- Search for `testCase === 'refresh-ssg’`
## Credits
Based on the [Simple Website CMS starter template](https://github.com/directus-labs/directus-templates) by Directus
Labs.
## License
MIT