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 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, 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

   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:

    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 <your-token> and the correct DIRECTUS_URL.

   DIRECTUS_URL=http://localhost:8080
   DIRECTUS_FORM_TOKEN=<your-token>
   DIRECTUS_SERVER_TOKEN=<your-token>
   NUXT_PUBLIC_SITE_URL=http://localhost:3000

4. Now, install the Directus template.

   cd template && npm run setup-directus

   On Windows, apply the Directus template with the directus-template-cli to populate your instance with the required schema and content. Run this from the repo root and make sure to replace <directus-url> with your Directus URL and <your-token> with the token you generated earlier.

   npx directus-template-cli@latest apply -p --templateLocation=./template --templateType=local --directusUrl=<directus-url> --directusToken=<your-token>

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:

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 <script> 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

# 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 by Directus Labs.

License

MIT