There are two files you'll find in your project that are important for Webiny: webiny.root.js and webiny.config.js.


This file is always located in your project's root and is unique. Our CLI relies on this file to find the project root when you run it from project folders that are not root.

  • template - this property contains the name and version of the project template you used to bootstrap your project. It may not be very important to you at this point, but it will help us to provide you with migration tools and other support in the future.

  • projectName - generated using your project folder name. This one is used to name resources during deployment of infrastructure to the cloud. It will help you to look for specific resources in AWS Console.

  • cli

    • plugins - an array of CLI plugins. You can easily add your own CLI plugins here to expand the Webiny CLI capabilities.

Here's what this file may look like in your project:

module.exports = {
template: "@webiny/[email protected]",
projectName: "my-project",
cli: {
plugins: [


You will find this file in each package that represents an app or an API resource. In this file we define:

  • commands - arbitrary functions to be executed by yarn webiny run [command]

In the future, we may add more features in here, but for now it's just commands.

This file gives you a way to create your own commands to handle your code, by writing simple functions. We provide a lot of utility functions in our @webiny/project-utils package for you to use for bundling apps, functions, etc. A good example is found in apps/admin/webiny.config.js. The example below shows a simplified version of the aforementioned file:

// webiny.config.js
const { startApp, buildApp, buildAppHandler } = require("@webiny/project-utils");
const { setEnvironmentFromState } = require("@webiny/cli-plugin-deploy-components/utils");
const map = {
REACT_APP_USER_POOL_REGION: "${cognito.userPool.Region}",
REACT_APP_GRAPHQL_API_URL: "${cdn.url}/graphql",
REACT_APP_API_URL: "${cdn.url}",
REACT_APP_FILES_PROXY: "${cdn.url}",
REACT_APP_USER_POOL_ID: "${cognito.userPool.Id}",
REACT_APP_USER_POOL_WEB_CLIENT_ID: "${cognito.appClients[0].ClientId}"
module.exports = {
commands: {
async start({ env, stack, ...options }, context) {
// Set environment variables from state
await setEnvironmentFromState({ env, stack, map }, context);
// Start local development
await startApp(options, context);
async build({ env, stack, ...options }, context) {
// Set environment variables from state
await setEnvironmentFromState({ env, stack, map }, context);
// Bundle app for deployment
await buildApp(options, context);
// Build Lambda handler which will serve files to CDN
await buildAppHandler(options, context);

With this you defined a webiny.config.js file and 2 commands: start and build. The most common way to run them is by adding a script to your package.json located right next to the webiny.config.js file:

// package.json (most of the file contents is skipped to focus on the example at hand)
"scripts": {
"start": "env-cmd -r .env.json -e default webiny run start --env=local --stack=api",
"build:dev": "env-cmd -r .env.json -e default webiny run build --env=dev --stack=api",
"build:prod": "env-cmd -r .env.json -e default webiny run build --env=prod --stack=api"

You can also run the command by calling yarn webiny run [name].

Command parameters

Every command you define will have the same parameters, options and context:

  • options - is an object containing input parameters parsed by yargs which we use under the hood for our CLI. By running yarn webiny run myCommand --custom=value, yargs will parse that command and your custom parameter will be accessible via the options.
  • context - this is a Context object provided by Webiny CLI. It contains helper methods, plugins and other useful information constructed at runtime.
Last updated on by Pavel Denisjuk