Development Workflow

In this article, we are going to share a step by step guide on developing workflow with Webiny.

Webiny Local Setup

First things first, we will fork and clone webiny-js repo.

  • Install all dependencies by running yarn

  • Run yarn setup-repo.

    What happens when we run yarn setup-repo?

The will set up the necessary environment config files and build packages to generate dist folders and TS declarations.

This task is possible by Lerna, we will explain below the importance of using Lerna.


Lerna optimizes the workflow around managing multi-package repositories with git and yarn in our case.


Yarn manages the workspaces and Lerna publishes packages and run commands across workspaces. In monorepo lingo, a workspace is a single package.

  • We will use Lerna to watch for changes in packages we are working on. The watch script transpile typescript files into javascript.

    We use --scope to watch a particular package.

    [email protected]/package_name as specified in the package.json itself.

  • Lerna will match the scope parameter, and will say that I found this package that runs into this path.

  • How to run watch in many scopes?

    [email protected]/package_name [email protected]/package_name --parallel

    :::info The parallel parameter will tell Lerna to run typescript compilations. This parameter is dangerous when you want to build packages. :::

  • We add the --stream parameter, to stream the output to our terminal.

  • Then we will run lerna run build --stream to build packages.

  • This is the only thing you need to do to have the developer cycle.


The same thing goes for API packages.

Going Live

Now that we have our project, it's almost ready to be deployed. To begin the development, we need to deploy an instance of an API for React apps to talk to.

The apps need to talk to an API, Webiny is serverless and we do not support a local API development. You will work with Lambdas, CDNs. The local environment is the only actual build in system. You need to deploy a local API, deploying an instance of API and we will use it for local development of our React app.

The resource file has the items which we will deploy, you can see the entire stack definition in here.

The file organization is open to developer decisions.

We notice that Webiny is set up as a monorepo so we can manage our packages, for both API and React.

This is the reason we use yarn because its workspace management makes working with monorepos enjoyable.

Check out our project structure and content here.

When you navigate to packages you will see around 70 packages. We also have the sample-project folder. This is the project which the user will get when creating a new webiny project. The sample-project is the project we simulate users project, we will use it as a sandbox.

  • Deploy your API by running npx webiny deploy api --env=local from the sample-project folder.

Webiny should run from the root of the Webiny project. Since sample-project folder is a sandbox, this is the place to run your webiny commands from.

Run npx webiny --help to see the available commands in our CLI

  • Once deployed, it will update your React apps .env.json files with the necessary variables.

Now we have headless cms configured, which has its entry point, the one thing we care about is the main GraphQL API. It can take from 3 - 15 minutes to be available.


Within our repository, you should use npx to run Webiny CLI.

For example, npx webiny deploy api --env=local

Why? Because npx will resolve the CLI binary to the node_modules in the root of your repository.

  • Begin working on React apps by navigating to sample-project/apps/{admin|site} and run yarn start.

  • React apps are regular create-react-app apps, modified, but all the CRA rules apply.

  • When working on a particular package run lerna run watch --scope=name_of_package. It will build your changes into the corresponding dist folder.

    React app build will rebuild and hot-reload changes that happen in the dist folder of all related packages.

  • The easiest way to run a watch is by running lerna run watch --scope=name_of_package --stream --parallel.

Now that we set up webiny project, we can notice that webiny is set up as a monorepo so you can manage your packages, for both API and React.

This is the reason we use yarn because its workspace management makes working with monorepos enjoyable.

What happens when we build packages?

Let's see an example package, the api-cookie-policy.

Package content

The package contains the dist and the src folders.

The dist folder will be where our actually compiled code will take place, from there we will be able to publish to npm right away.

The src folder will be the place where we will write our code.

We have two tsconfig files:

  • - contains base configuration for developing using typescript.
  • tsconfig.json - extends and is configured to play with your IDE for instant type checks.

Since we have src and dist folders, yarn links packages as workspaces. Each package is a separate workspace.

One important thing for development is that when you change something in these packages in the src

When adding changes in src folder in these packages, we need to run build on that particular package. The build compiles the code and puts it into the dist folder.



We have a tool called postinstall hook, which improves the handling of packages. This tool links packages to their dist folders or the configurable packages of yours.

As we mentioned earlier, each workspace is considered a separate npm package. The publishConfig is an npm directory config parameter. When we run publish, package linking will work based on the publishConfig setup. Lerna will get the information from the publishConfig parameters, where the compiled code lives.

"publishConfig": {
"access": "public",
"directory": "dist"
Last updated on by Albiona