Heads up! This article was written before Webiny 6.0 was released and may contain outdated information.
Webiny uses over 100 interdependent packages. Testing locally ensures changes don’t break anything before publishing them publicly.
Webiny is the AI-programmable CMS that gives enterprises full control. Build, extend and automate your content operations with a platform designed to be shaped by both developers and AI agents.
Verdaccio is a lightweight private npm proxy registry. It lets you publish and install packages locally, mimicking a real NPM environment for testing.
Run yarn verdaccio -c .verdaccio.yml from the project root. This starts Verdaccio using Webiny’s custom config.
For npm:
bash
CopyEditnpm config set registry http://localhost:4873
For Yarn v2+ (Berry):
Create a .yarnrc.yml file in your home directory with:
yml
CopyEditnpmRegistryServer: "http://localhost:4873"
unsafeHttpWhitelist:
- localhost
Use this command:
bash
CopyEditnpx create-webiny-project@next test-project --tag next --no-interactive --template-options '{"region":"us-east-1","storageOperations":"ddb"}'
We want to provide the easiest way for developers to get started when building a new Webiny project. So we have a create-webiny-project command line interface (CLI) that creates a new user project with their chosen AWS region and some other preferences they need.
This CLI requests over 100 packages which are published to NPM. These all work together to create GraphQL APIs, the Admin interface, and infrastructure-as-code that allow our four interrelated applications to work together.
Modifying these packages and testing them could prove to be a challenge if it wasn't for very useful tools like Lerna, which we use to publish new versions to NPM, and Verdaccio. Verdaccio is a proxy registry. That means when configured it intercepts requests to NPM, and serves packages you've published to it locally.
Here's how we use leverage Verdaccio to test packages at Webiny, using our repository as an example.
First of all, edit something in a package and build it. Then start Verdaccio. We can do this from the webiny-js project root directory using the following command:
yarn verdaccio -c .verdaccio.yml
The flag -c tells it to accept the config file we already have set up in the project.
Next we need to set the registry address to use the port Verdaccio is running on instead of NPM's (https://registry.npmjs.org) By default this is port 4873. Run this command to change the registry address:
npm config set registry http://localhost:4873
Did it work? To check, you can cat ~/.npmrc, you will hopefully see the following:
registry=http://localhost:4873
If you're running Yarn v2 or greater, Yarn no longer recognizes this config file. Instead you will also need to create a .yarnrc.yml in the user root folder with the following parameters:
npmRegistryServer: "http://localhost:4873"
unsafeHttpWhitelist:
- localhost
There's more information about this on Verdaccio's docs site.
The final steps before we test our user project is to create a new Beta version and release the packages. This is where our existing setup in the Webiny project with Lerna steps in. You can see details of how this command works by looking at the package.json in our repository.
yarn lerna:version:verdaccio
Under the hood this runs the Lerna version command but doesn't push or create a changelog. It also creates a new tag for the release. If this is the first time you've run the command, the tag will be v{version}-beta.0, then v{version}-beta.1, and so on. Once this has completed you will see a new release commit on the branch which you will need to roll back afterwards. Now we can release the new version to Verdaccio.
yarn lerna:publish:verdaccio
This takes the existing packages with the appropriate tag and publishes them to our local Verdaccio registry. Please note that if you are running Verdaccio on anything other than the default port you'll need to run the full command:
yarn lerna publish from-package --dist-tag next --registry=\"http://localhost:{port}\" --no-verify-access --no-verify-registry --yes
The next step is to create a new Webiny user project. You can create it in a subdirectory of the webiny-js repo, or in another folder. We can use NPX to do this using the following command:
npx create-webiny-project@next test-project --tag next --no-interactive "unsafeHttpWhitelist":["localhost"]}' --template-options '{"region":"us-east-1","storageOperations":"ddb"}'
You can of course replace test-project with something more relevant, and set it to deploy to a different AWS region other than us-east-1 if you wish.
Once this has finished you should be able to run yarn webiny --version and see your newly published beta tag.
You can now deploy your project as normal and test any changes you made.
Once you have some changes you need to make, or you're satisfied that your changes won't break anything, you need to roll back your system and the webiny-js repo to it's previous state.
Stop Verdaccio
Point local registry back to npmjs.org:
npm config set registry https://registry.npmjs.org
rm ~/.yarnrc.yml
# if you think you might need this file later, you can instead do
mv ~/.yarnrc.yml ~/.yarnrc.yml.bkup
git reset --hard HEAD~
git tag -d ${tag}
As you can see, Verdaccio is very easy to use, and in fact we have hardly spent any time configuring Verdaccio since it has been set up. For the most part, we've used the default configuration. Leveraging Lerna's ability to publish packages quickly and easy has meant that we can concentrate on delivering great software instead of spending more time on our tooling.
If it helps, we also created a video of this process:
Happy coding!