Project Structure

In this article we'll look at the project structure and explain the responsibilities of certain files.

Once your project is set up, it will look like this:

├── api/
│   ├── .serverless/
│   ├── .env.json
│   └── serverless.yml
├── apps/
│   ├── .serverless/
│   ├── admin/
│   ├── site/
│   └── serverless.yml
├── packages/
│   ├── project-utils/
│   └── theme/
├── .env.json
├── .gitignore
├── .prettierrc.js
├── package.json
└── webiny.js

It is set up as a monorepo so you can easily manage your packages, for both API and React, from within the same repo. This is the reason we use yarn - its workspace management makes working with monorepos really enjoyable.

A Webiny project consists of an API and React apps. Those are located in api and apps folders, respectively. You should not rename those two folders as our CLI counts on those to exist.


This folder contains the serverless template file, serverless.yml, used by the Webiny CLI to deploy your API. It also contains an environment config file, .env.json, with as many environments as you need. Where's the code? The code is generated by our serverless components at deploy time and you'll be able to see the generated code after your first deploy in the .webiny folder.

Adding new APIs is a matter of editing the serverless.yml file and adding new components and plugins. More on this in separate articles about API development.


This folder also contains a serverless template file to deploy your apps. The admin and site apps are regular React apps created using create-react-app. However, we use rescripts to override some things in the original react-scripts without ejecting. Don't worry - no magic here. The package responsible for all the customization is located in your project, in packages/project-utils and you can change it as you wish.

Why rescripts?

react-scripts package does not support monorepos, so to enable our apps to resolve packages in the monorepo, and transpile them on-fly, we had to override some parameters. There's more to this package, so dive in and take a look at it yourself.


This folder is for you to use for whatever custom packages you may add. By default, it contains the theme package, which is used by both admin and site apps, and the aforementioned project-utils.

NOTE: when you add new packages, makes sure you link them with your monorepo by running yarn in the root of your project. This will create symlinks to the node_modules and your packages will be accessible from anywhere within the project.

Other files

  • .env.json - contains environment variables that are used when you deploy both api and apps, so you can set shared variables in this file. This file is loaded first, then the api/.env.json values are merged into it (same goes for apps/.env.json in case you have it; by default, it is not needed).
  • webiny.js - this file is used by our CLI to get the location of React apps. If you add more apps to apps folder, make sure you also add it to the webiny.js file. We may add more configuration options to this file in the future.
Last updated on 2019-11-15 by Pavel Denisjuk