Developer Onboarding Guide

Introduction

Welcome to the Developer Onboarding Guide for Webiny!

Whether you’re new to Webiny or looking to deepen your existing knowledge, this guide is designed to provide you with a foundation for working with Webiny.

In this guide, you will explore the prerequisites needed to make your development process smooth and efficient. We’ve included a curated list of resources to assist you. These links will guide you through tutorials and documentation, enabling you to leverage the full potential of Webiny as you progress in your development journey.

Webiny Overview

Webiny is an open-source content management system designed for enterprises. It’s built on top of the serverless infrastructure to enable great scalability and site reliability even in the most demanding periods.

Webiny is not your traditional CMS, nor your typical headless CMS. Webiny includes a set of applications that cater to a broad set of cases. Applications that come with Webiny are:

• Headless CMS
• Page Builder
• Form Builder
• File Manager
• Advanced Publishing Workflow
• Webiny Control Panel (also referred to as WCP)
• Admin

Serverless Architecture

Webiny is built on a serverless infrastructure to ensure excellent scalability and reliability, especially during peak traffic periods. Serverless computing lets you build and run applications and services without thinking about servers. It eliminates the need to manage infrastructure for your applications. In the serverless world, your cloud service provider takes care of provisions, scales, and managing infrastructure required to run the code.

Install Webiny

Start your Webiny project quickly by deploying it into your AWS account. Follow the detailed steps in our guide to install Webiny.

Core Development Concepts

In this section we will look into some core development concepts that can help you in development with Webiny.

Plugins

Plugins are the fundamental building blocks in Webiny; everything is composed of plugins. So, if you’re wondering how to build or customize something within Webiny, the answer is typically to write a plugin for it. Whether you’re adding a feature or making a customization, you’ll find that nearly all enhancements in Webiny are achieved through plugins. Our documentation provides detailed guides on how to create plugins for various functionalities and customizations.

Webiny CLI

Webiny CLI (command line interface) is the central tool that you’ll be using throughout the complete project development process, in your terminal of choice.

Project Applications

Webiny uses the term project application (or just application) in order to depict a specific logical segment of your project. Project applications are higher-level organizational units formed from one or more packages that, as the name itself suggests, form applications. Every application, essentially, consists of two pieces:

• Your application code, which includes one or more Node.js packages.
• Cloud infrastructure that hosts your code or which is being utilized by it, which is also described and deployed using code.

Monorepo Organization

Every Webiny project is organized as a monorepoexternal link. This essentially means your project is organized as a collection of multiple NPM packages, or, in the context of monorepos, multiple workspaces.

Tools & Libraries

Project Deployment

Webiny makes it easy to deploy your project, using the Webiny CLI and Pulumi as the default infrastructure as code and deployment solution. You can also easily deploy your project into multiple environments.

Local Development

Serverless development has slightly different principles from traditional application development. In the traditional development process, developers typically develop and test their project locally before deploying it to a server. However, in the serverless world, this process is slightly different.

Infrastructure

Project deployment is an important part of an application development lifecycle. Essentially, deploying your project entails the deployment of necessary cloud infrastructure resources with the application code you wrote. It can be done from your machine directly, which is usually the case when developing, or from a remote environment, for example CI/CD systems, that, based on provided instructions, deploy your project automatically for you.

Architecture

A Webiny project consists of four project applications:

1. Core (./apps/core) - defines core cloud infrastructure resources
2. API (./apps/api) - your project’s (GraphQL) HTTP API
3. Admin (./apps/admin) - your admin area
4. Website (./apps/website) - your public website

If we wanted to compare these applications by the complexity of the cloud infrastructure, we could say that Core and API are the most complex ones. This is simply because these deploy more different cloud infrastructure resources than the remaining Admin and Website project applications.

Environments

Your project can be deployed into multiple environments. This means that you can have multiple “copies” of your project up and running at the same time, each having its own name and purpose.

Preview Deployments

During the project development, there is a chance that the deployed cloud infrastructure needs to change. New resources might be added, existing resources configured differently, and some may even need to be destroyed.

When doing more significant changes, it might be helpful to preview the deployment process that you’re about to execute. More specifically, you would certainly like to know if the deployment you’re about to execute destroys a mission-critical resource, e.g. a database or a file storage resource.

Deployment Modes

The Core and API project application can be deployed in two different deployment modes: development and production.

Destroy Cloud Infrastructure

Modify Cloud Infrastructure

Infrastructure Best Practices

CI/CD

The process of application development is much more than just writing application code. It entails several different subprocesses, which are equally, if not more, important. For example:

• testing
• deployment into multiple environments
• organizing code in multiple Version Control System (VCS) branches
• choosing the right cloud infrastructure resources for the job
• storing and managing cloud infrastructure state files
• security
• monitoring and observability
• team organization

In the our documentation, we cover some of these subprocesses and provide best practices around how to structure and implement them, within your CI/CD workflow.

Applications

The main applications Webiny are Headless CMS, Page Builder, Form Builder, File Manager, and Admin. Each application can operate independently, offering specific functionalities tailored to various needs. However, they are also designed to work together seamlessly, providing a cohesive and integrated experience.

In the upcoming section, we will delve into these main Webiny applications and explore common customizations. To further assist you, we have created End User Guides for each application, it will be linked in the sections below for easy access.

Headless CMS

A scalable GraphQL-based headless CMS built on top of serverless infrastructure.

User Guides

GraphQL API Overview

The Headless CMS Webiny application comes with a fully-fledged GraphQL API, which you use in order to perform GraphQL queries and mutations on Headless CMS content models, groups, and entries.

Define Content Models via Code

Content models and content model groups can be defined in two ways

• Via the Admin Area
• Via code (Using Plugins)

Page Builder

No-code page builder. Build pages in minutes using a drag&drop interface.

User Guides

Pre-Defined Webiny Blocks Library

Webiny offers free library of over 100+ professionally designed, fully responsive page builder blocks that you can use in your Webiny Page Builder. These new pre-built visual blocks will empower you to effortlessly create stunning pages in no time.

Create a Custom Page Element

Out of the box, Webiny’s Page Builder app provides a plethora of ready-made page elements we can use to create both simple and complex pages for our website. Furthermore, on top of the default set, users can also create their custom page elements via plugins.

Extend Page Settings

Page settings UI within the Webiny Page Builder, by default, contains 3 major sections: General settings, Social media, and SEO settings. You can extend page settings and add new fields to it.

Theming Best Practices

By default, every Webiny project includes the default website theme which defines different visual aspects of your website, for example the default set of colors, typography, the default page layout, and more. It is managed via theme.

Form Builder

No-code form builder. Build forms in minutes using a drag&drop interface.

User Guides

Theming Introduction

When you’re creating forms in the Form Builder, you have the option to preview forms right there inside the same interface. How the form looks visually is controlled via the form layout that is selected for that form. The default theme includes a single form layout which should fit most use-cases. If you wish to do any visual tweaks, it’s best to just modify the stylesheets.

For more advance case you might want to create a custom form layout. The best approach would be to copy the existing one and update the things you need to adapt.

File Manager

A scaleable digital asset management application built on top of serverless infrastructure.

User Guides

Create a File Type Plugin

By default, the Webiny File Manager has a preconfigured plugin for image files, and a fallback plugin to render any other file type using a default icon. You can implement your own renderers for file types of your choice.

Programmatic File Upload

Upload of files into the File Manager is a 3-step process, which is described, from the architectural point of view, in the File Upload article. Very often, files can be several gigabytes (or even terabytes) large, which makes it impossible to use the GraphQL API, or even a REST API, to upload binary content using the Lambda functions, which power our API, due to its physical limitations.

Admin Area

Webiny CMS is a unified product that consists of several apps. To access them, you use the Admin app. The Admin app not only contains ready-made apps, but also provides a framework for developers to extend their functionality, and develop custom ones.

Basics - the Framework

Admin app is powered by a simple React framework, which allows you to add new React Context providers, compose existing UI components, register routes, and do all that using plain React components, and widely used concepts, like Higher Order Components (hereinafter: HOCs), and hooks.

Change Logo

You can change the default Webiny logo to your own logo in Admin application. Changing the default logo is a very quick and straightforward process.

Custom Dashboard

You can customize the default dashboard in Admin application.

Release Management

Branching Strategy

At Webiny, we like to release versions relatively often (in 2-3 weeks cycles), so our users get all the new features and bug fixes that we add to the product. We have a quarterly major release cycle during which we launch significant new features.

However, since Webiny is not a simple library, upgrading between project versions can be cumbersome, and not all users want to do it that often. Sometimes, upgrades require code mods to modify your project files, database migrations get executed, so it’s a bit more complex than just pulling in a new NPM package version.

Release Notes

We maintain a dedicated section for Release Notes, Upgrade Guides, and Change Logs to help you stay updated and efficiently manage upgrades.