Troubleshooting tips for some frequent 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.
node_modules folder might not be up to date.
Sometimes a project's
node_modules directory can become contaminated or out of sync:
rm -rf node_modules
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
npm install and
gulp devand not
If you're getting an error building your CSS or JS, make sure you're running the
gulp vf-dev should only be invoked from the command line when
vf-core, for other projects run
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
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).
You might have an incompatibility between component versions or
you've recently updated, rollback version and re-run
gulp dev. If that fixes
issues, consult the component
CHANGELOG.md files or read up on the
In your local component directory, you should have symlinks to where you keep
your Yarn-installed components, such as
../../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.
Your local files might be out of sync, stash your local changes elsewhere and
git reset --hard.
If you're at a loss, you can discard all untracked files and non-committed edits
git clean -fxd.
This will remove many things including
node_modules, so you'll need to run
Windows has its own unique needs and section of tips.
And within that we recommend using PowerShell. Here's how to install Terminal.
If you need to install, node, yarn and all the things, use
Windows need some extra love with path handling, this can usually be sorted
let myFixedPath = myPath.replace(/\\/g, '/');
The Visual Framework utilises symlinks, these work fine on Windows but they will need to be initialised on your first git pull:
cmd /c mklink /D .\src\components\vf-core-components ..\..\node_modules\@visual-framework\
Find an issue on this page? Propose a change or discuss it.