This should include:
How to use cli-scaffold to develop new graphql services
How to use scaffolding
What it generates.

Prerequisites

1. Setup webiny-js repo - this is where Webiny is located. You're gonna want to read the Contributing document.

2. Clone this repository - this is where you'll write the actual docs (the whole site is based on Docusaurus V2). A short intro can be found in the README file.

Introduction

Once a new Webiny project is set up, out-of-the-box, users get access to the Admin app, which looks like this:

The above image actually shows the Page Builder app, which is just one of the apps Webiny offers out of the box. If we open the main menu, located on the left side of the screen, we can see the other apps as well:

Who can access these apps?

Every time a new Webiny project is deployed, in a short installation wizard, users get to create the initial "full access" admin user, which, as you might have already guessed, can access everything in the system.

After that, via the Security app, we can create additional users, with a specific set of access permissions.

How do permissions work?

The Security app uses the following structure:

Security Scopes <  Security Roles < Security Groups

So, it all starts with "security scopes", for example: page:read, page:create, page:publish, and so on. Then, in order to group one or more scopes together, a "security role" can be created, for example, "Security - Roles", which could contain all scopes needed to be fully able to manage roles. Another example would be "Page Builder - Pages" - this allows the user to fully manages pages as well. Finally, the user can also group roles by creating "security groups". An example of a security group could be "Security - Full Access", which, as the name of the security group states, gives complete access to the Security app.

The task

Now that we have an overview of how security is organized, we can proceed to the actual task.

We want you to document a couple of components and helper functions that our Security app offers, which help developers to check current user's permissions (scopes, roles, groups) easier, and act accordingly.

The Security app actually consists of two packages:

• @webiny/api-security - the backend GraphQL API
• @webiny/app-security - the React app (plugged into the mentioned Admin app)

API

On the API side, the Security app offers a couple of neat helpers.

For doing checks on the GraphQL schema level and restrict executing a resolver, we offer hasScope and hasRoles helpers. There a really a lot of examples in the existing codebase because we used this in all of our apps:

• packages/api-security/src/plugins/graphql.ts:68
• packages/api-page-builder/src/plugins/graphql.ts:91
• packages/api-form-builder/src/plugins/graphql.ts:93

Note that for now, we didn't have the need to utilize the hasRole, but it's there and it should be documented.

App

React Components

On the app side, the Security app offers two React components: SecureView and SecureRoute.

Again, there are a lot of examples.

We used SecureView component for deciding whether or not menu items needs to be shown:

• packages/app-security/src/admin/plugins/menus.tsx
• packages/app-page-builder/src/admin/plugins/menus.tsx
• packages/app-form-builder/src/plugins/menus.tsx

Also, we used SecureRoute to decide if the complete route needs to be rendered:

• packages/app-security/src/admin/plugins/routes.tsx
• packages/app-page-builder/src/admin/plugins/routes.tsx
• packages/app-form-builder/src/plugins/routes.tsx

Note: the difference between the two is just in the fallback render. While SecureView doesn't render anything at all, the SecureRoute will render a default You are not authorized to view this route. message (can be customized via a plugin as well).

Helpers

With shown components, the app also offers hasScopes and hasRoles helper functions. Might be useful when coding non-React logic.

How to write the docs?

Please check our other documentation pages, to get a feel of how we've approached it. These are some of the latest Admin app articles we added:

• https://docs.webiny.com/docs/webiny-apps/admin/development/header
• https://docs.webiny.com/docs/webiny-apps/admin/development/menus
• https://docs.webiny.com/docs/webiny-apps/admin/development/routes

Organisation

I would create two categories in the Webiny Apps > Security > Development section: App and API.

In there, in the API section, I would maybe create the "GraphQL" menu item, which would point to a page that describes the above shown API/GraphQL helper functions.

For the Apps section, I would create React Components and Helpers, where you could describe the shown components and helpers.

Not 100% about both suggestions, if another idea comes to your mind, feel free to let us know.

Bonus

The other day, I noticed that we might add another, more practical example, into the Menus article.

So, at the end of the article, just add a new title, name it for example "Menus with the Security app" (or something along those lines), and create a simple example, that shows how you can create a menu, and also have it rendered only if a security check has passed.

Cross-linking is encouraged, so feel free to link the Security app as well. Often we like to use quote sections for these quick tips:

The same could be done with the Routes article as well.

Description:
Rename: webiny deploy-apps to webiny deploy apps (and other similar references to webiny deploy-x)
Update api:
No longer use serverless.yml, we use resources.js
Update graphql-services:
@webiny/serverless-apollo-service replaced with @webiny/serverless-function

Remove: (These services consist of an API Gateway and a function which runs your GraphQL API.

The API Gateway serves as a router and an entry point to your service. This way you can access your GraphQL API function via a simple HTTP request to {api-gateway-url}/graphql. Some services may also provide other REST routes if needed.)

Update apollo-federation:
Replace:
@webiny/serverless-apollo-gateway
with
@webiny/serverless-function
Replace:
To access this main entry point, we deploy another API Gateway with a single route /graphql.
with:
To access this main entry point, we deploy an API Gateway with a single route /graphql.
Update app-as-a-function:
Polish:
When React apps are deployed to the cloud, each app is deployed as a single function. For the site app, we also deploy another function that serves as a server-side rendering (SSR) function. It is invoked by the site handler when it determines the content needs to be rendered.

Update:
'apps/site/src/plugins/index.js' with proper app template

Some users encountered Missing credentials in config but they did have AWS configured. The problem is, they configured a custom profile, so we need to add a note to tell users to update the {projectRoot}/.env.json with their AWS_PROFILE in case it is not default.

Update Summary:
Change Summary so it doesn't include refs to:
graphql-schema
graphql-context

graphql-context is now context
Replace GraphQLContext -> Context

Double check to see if SecureRoute and SecureView are both necessary.

Update summary:
Remove
form-editor-field-group
form-editor-field-type
headers

Image needs to change to this

adding-security:
Adding Security title potentially renamed to 'Adding Protection to Menu' (or something similar)

replace ~@webiny/app-page-builder-theme/src/styles.scss
with ~@webiny/app-page-builder-theme/styles.scss

In this article: https://docs.webiny.com/docs/get-started/quick-start we should remove the link to Youtube for AWS setup, as it is confusing people. It references SLS framework, and we don't use it.

Instead it's best to point users to AWS docs on configuring credentials:
https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html

Prerequisites

1. Setup webiny-js repo - this is where Webiny is located. You're gonna want to read the Contributing document.

2. Clone this repository - this is where you'll write the actual docs (the whole site is based on Docusaurus V2). A short intro can be found in the README file.

Introduction

Once a new Webiny project is set up, out-of-the-box, users get access to the Admin app, which looks like this:

The seen user interface is built using the concept of plugins, which is a very flexible way to add, remove, or alter existing functionality. Basically, a plugin is an object which consists primarily of type and name properties, and one or more custom properties that are needed to get the job done. For example:

{ name: "my-plugin-xyz", "type": "my-plugin", ...otherXYZProps }

A good plugin usage example is the top bar in the Admin app, which utilizes three different types of plugins:

Who registered these plugins?

The answer is the @webiny/app-admin package (located in packages/app-admin), some examples can be found here:

• Global search in the middle - packages/app-admin/src/plugins/GlobalSearch/index.tsx
• Logo on the left - packages/app-admin/src/plugins/Logo/index.tsx
• User menu on the right: packages/app-admin/src/plugins/UserMenu/index.tsx

All plugins that the @webiny/app-admin package exports can be found here: packages/app-admin/src/plugins/index.ts

Where are these plugins imported?

You might be asking yourself, OK, I see this bunch of plugins, but how are they used? In the case of the Admin app (there is the Site app as well, but never mind that for now), all of the needed plugins are imported here apps/admin/src/plugins/index.js.

The task

Your task is to play around with Webiny, and try registering additional components in the top bar. Once you've managed to do that, we want you to document it, so other users who will be using Webiny, know how to do it.

We already have Adding routes and Adding menus articles, so you can put your article here as well:

We can call it "Header Elements".

Please check the linked articles to get a feeling of how we approach the docs and what level of detail we like to apply.

Plugin reference

Make sure to also add these plugins and short "more-formal" details in the Plugins Reference > App page.

I've added some boilerplate text already for you in the docs/webiny-apps/admin/development/plugins-reference/app.md. It's all commented out, so remove the comments and just fill in the blanks.

I updated our app-admin package in a way that plugin types (both TS and actual plugin type field) now include the admin- prefix. It helps with autocomplete and also creates kind of a namespace for plugins within admin app.

We will need to update Admin app section of the docs to include this change:

Project structure should be updated with 'create-webiny-project' folder structure

'You should not rename those two folders as our CLI counts on those to exist.' is no longer true, this can be removed.

Update #api/apps/packages/Why rescripts/Other files?
Update each of these with the create-webiny-project folder structure, but keep the organization or thought process/description of the same line of thinking.

Remove:
Let's try to showcase what you can achieve with Commodo, in a quick and clear way.
(unneeded as next line is The basics)

Update reusing-fields-with-a-custom-hof:
Uppdate this to include pipe:
(Utilize functions like flow (from lodash library) or compose (from rambda library) to make your code much more readable.)

update configuration-overview:
Code example replaced because plugins folder no longer exists:
// apps/site/src/plugins/index.ts
update pb-page-layout-plugin (similar issue)
update pb-layout-component (similar issue)

Look for reference in Form Builder

We need to explain what webiny.root.js and webiny.config.js do and how to configure them

The motivation here is that Guides, FAQ, and How To Contribute need to be more visible to the end-user.

1. Guides should be a top level menu item
2. FAQ should be within Webiny sub-menu
3. How to Contribute within Webiny sub-menu

Update: plugins-in-graphql
update package import from @webiny/api to @webiny/graphql
(@webiny/api this does not exist any more)

cloud-native-development can be linked to FAQ as an answer to the original question asked.

Update how-we-do-it:
On watch mechanism
Bonus: Create article about development workflow

Update graphql-schema-tests:
"@webiny/api/" reference to "@webiny/graphql/"

Some users reported the following error during admin app build: Allocation failed - JavaScript heap out of memory.

This is not something we can solve ourselves, but a solution is to increase the amount of memory available to node process, by settings:

NODE_OPTIONS=--max_old_space_size=4096

Roadmap for this menu:

1. Anatomy of an app
2. Creating/Customizing your own plugins
3. Customizing your build process
4. Customizing your own Stylesheet
5. How to customize site Layout for an application
6. How to override different plugins

Update Security Service Architecture Graph: Diagram
Regarding usage of Personal Access Token validation (PAT)

When running deploy-apps, the desired environment config may be missing:

1. add a suggestion to run webiny deploy-api --debug --env={env}
2. improve this article so it is clear that apps env depends on the existence of the corresponding API env

Update registering-a-theme:
Update paths for apps/site/src/plugins/index.ts

Example and explanation needs to be updated with react-app-template

-Under create dev environment config:
api/.env.json Mongodb credentials have moved over to their own config file.
-Deploy API using dev environment
webiny deploy api --env=dev
-Deploy apps using dev environment
webiny deploy apps --env=dev
Update:
"build:staging": "env-cmd -r .env.json -e default,staging rescripts build"
To the new command

Note:
Maybe make it more clear to users what the deploy means for their development workflow.

update creating-a-plugin:
Capitalize first word so it looks like:
NOTE: Don't try to create a plugin in your code just yet. Simply go through this section to get an idea of how plugins work. There are more articles on concrete plugins in the docs that will be easy to follow if you understand the concept.
Again here:

NOTE: We strongly recommend you create your plugins as factory functions. That way it is easy to add configuration that affects how plugin behaves. For API plugins, factory is a requirement.
Replace:
If you have already created a Webiny project, you can find examples of plugin registration in the following files:
apps/admin/src/App.js
apps/site/src/App.js
With
apps/admin/src/App.tsx
apps/site/src/App.tsx

Update the way we interact with react-apps (this specifically references the way we use registerPlugins)

update using-your-plugin:
Make this text more concise:
The last thing to do is get your plugin(s) and use them the way they are meant to be used.

Remove this article

We removed aws credentials from .env.json files into the global config in ~./aws/credentials .
Include this step in the Getting Started or where it is relevant in the documentation.

Task roadmap

1. Add documentation for plugins (both apps and api)
2. include screenshot of an example of a File Manager
3. Description of resources of File Service Architecture, code examples included (ideally)

Remove use of roles in example

Translation is WIP
Roadmap is blocked by that task.

1. How to create locales
2. api section in graphql

We had a question from a user who was a bit confused how the .env.json files work.

We must create an article which will give an overview of all files, explain how the inheritance works and how they are used - both by users that deployed a new project, and by other team members who are just cloning the project on their own project and starting from there.

Hopefully, we'll also transform our .json files to .js, so we'll be able to add comments in the actual files as well.

federated Federated GraphQL services
remove typo

Update request-flow:
Under 1.
Confirm that this is still valid:
'Webiny also supports REST services. In that case the endpoint path will be different. For REST endpoints the request is routed directly to the function of a federated GraphQL service, without the (C) Apollo Gateway in between.'

Remove sub-headers from Summary
security-scopes-list
secure-route-error

We can selectively deploy components using --alias=xyz parameter(s). Add a note to Development principles mentioning this parameter.

Check code example regarding MenuRenderComponent

Under Tools used:
Serverless Components needs to be replaced (with a reason, perhaps another link) on the new method and motivation for doing so.

update button-element:
Replace anything with "webiny-cms"
to "webiny-pb"

Create a simple article that explains how to register a simple menu in the Admin UI.

To add a menu, users need to register a specific MenuPlugin (packages/app-admin/src/types.ts:43) plugin in the system. A nice example can be found here packages/app-i18n/src/admin/plugins/menus.tsx. You can find other examples by searching for menus.tsx in the project. That will show you even more examples.

Possible Solution

Create a menu category and an article

For starters, I would create the following menu category (via website/sidebars.js):

In it, you can then create an article called "Registering menus", which explains how to do it. Screenshots and linking other pages is encouraged. For example, usually, we like to link this plugins crash-course when we talk about plugins in the article.

Also, take a look at our other pages, to get a feel of how we like to approach writing docs. Your docs should follow the same style, we want the docs to be uniformed.

Add plugin reference entry

If you open webiny-js: packages/app-security/src/types.ts:44, you will see we also have a short description and a link to the plugin page on our docs site:

This is cool because users can have this info directly in their code:

So let's add these for the MenuPlugin (webiny-js: packages/app-admin/src/types.ts:43) too. Note that you will have to add this in the webiny-js repo, so you will need to create a separate PR there.

For the docs, you can follow the same menu and content structure we have here. So, add the Development > App section in the proposed Webiny Apps > Admin menu, and c/p the content from the docs/webiny-apps/security/development/plugin-reference/app.md:10. Once you've done that, adjust the content to your needs.

Other information

Set up webiny-js

For this task, you will need to set up a new Webiny project first, not only because you will need to add the description and link to the MenuPlugin plugin docs article (explained above), but also because you will want to get the feeling of the whole system.

Clone the webiny/webiny-js repo. This is the repo in which the development of the Webiny platform is done. And once you've cloned the repo, check out the contributing docs to get started.

Note: in order to deploy a new Webiny project, you will need an AWS account. If you don't have one, contact the team.

Set up docs.webiny.com

For the actual writing of the docs, you need to clone this repo. Once you do it, run yarn in order to install all dependencies, navigate to website folder and run yarn start. That should spin up a local development server.

Note: the whole site is powered by Docusaurus, so feel free to check their docs if you need help (they have a good. We are using v2, so make sure you're not looking at the old version of the docs, which is the default.

How do you register plugins in your admin app?

If you open examples/apps/admin/src/plugins/index.js, you will see a bunch of plugins registered, coming from a lot of different apps, like app-page-builder, app-form-builder, app-security`, etc. For playing/testing purposes, here you can add your own.

Is this documented somewhere?

Not at the moment.

Bonus task - Routes docs article

You might have noticed we are also registering routes. So while we're at it, let's create the docs for routes creating, using same principles/approaches we described here.

1. Introduction- Overall description of what this layer does
2. User- High level description of User

• How to create a User

3. Roles - High level description of Roles

• How to create a Role
• How to search a Role

4. Groups - Higher level description of Groups

• How to create a Group
• How to search a Group

Roadmap:

1. How to protect your resolvers using scopes

https://docs.webiny.com/docs/deep-dive/project-structure

This needs to be updated to reflect the current/next project structure (packages folder no longer exists in the initial setup). Once headless is out, update this article to reflect the newest project structure, including webiny.config.js, etc.

Update layout-internals:
Example needs to be converted to typescript

Summary should not have the links to the functions at the top.
remove:
header-left
header-middle
header-right
menu
route

If you read the Quick Start and Deep Dive pages, you'll notice there's no text that mentions environments and the development approach Webiny suggests.

I would just add quick 2-3 sentences on the Quick Start page to make users aware of these things (this is a quick start - we do not want to get too much into details here), and a bit more detailed explanation on the Deep Dive page. We'll see, if required, we could even make a separate page for it.

The concept of environments is important, because, as far as the API/services domain is concerned, we are dealing with non-traditional "cloud-native" development, in which users have nothing deployed on their local machine, but do everything in the cloud. This is probably new to a lot of users (and a significant amount did ask about local development), so we should make it clear in the docs.

The client side development is still happening locally, so that should also be noted to the users.