Troubleshooting 🏚 😭 beta

Tips for things that can go wrong.

Many problems are due to local development environment configuration, here's how to get your development back on track.

Before creating a ticket or tossing your machine out the window, we've found most issues can be sorted by one of the below commands and tips.

Common commands and tricks

Run yarn install

Your node_modules folder might not be up to date.

Reset your project's build

Sometimes a project's node_modules directory can become contaminated or out of sync:

Don't npm install

Visual Framework systems work faster and are tested using yarn install. If you run npm install you may encounter unexpected issues or node may become confused if you're switching between npm install and yarn install.

Use gulp dev and not gulp vf-dev

If you're getting an error building your CSS or JS, make sure you're running the correct command. gulp vf-dev should only be invoked from the command line when developing vf-core, for other projects run gulp dev.

Update your components

If you're not getting the expected results, make sure your components are up to date. Most VF projects can update by running yarn run update-components. If that script fails, you can also try yarn upgrade-interactive --latest

You'll need to be using yarn for this to work (we recommend you use yarn and not npm for VF projects).

Rollback your components or vf-core version

You might have an incompatibility between component versions or vf-core. If you've recently updated, rollback version and re-run gulp dev. If that fixes issues, consult the component files or read up on the vf-core release notes.

Make sure there are symlinks inside your component directory

In your local component directory, you should have symlinks to where you keep your Yarn-installed components, such as ./src/components/vf-core-components which points to ../../node_modules/@visual-framework/. Sometimes these folders are manually deleted and not replaced by git origin pull, but git reset --hard will -- you’ll want to save any local changes first.

Git reset, hard

Your local files might be out of sync, stash your local changes elsewhere and run git reset --hard.

Git reset, harder 🚨

If you're at a loss, you can discard all untracked files and non-committed edits with git clean -fxd.

This will remove many things including node_modules, so you'll need to run yarn install.


Windows has its own unique needs and section of tips.

Use Windows Terminal Preview

And within that we recommend using PowerShell. Here's how to install Terminal.

Use Scoop for dependency management

If you need to install, node, yarn and all the things, use scoop.

Windows paths

Windows need some extra love with path handling, this can usually be sorted within node and gulp by let myFixedPath = myPath.replace(/\\/g, '/');

Symlinks and Windows

The Visual Framework utilises symlinks, these work fine on Windows but they will need to be initialised on your first git pull:

  1. Open PowerShell as an Administrator
  2. Delete the old symlink rm .\src\components\vf-core-components
  3. Recreate it cmd /c mklink /D .\src\components\vf-core-components ..\..\node_modules\@visual-framework\

Still stumped?

Make an issue or chat us.

Find an issue on this page? Propose a change or discuss it.