webiny / docs.webiny.com Goto Github PK
View Code? Open in Web Editor NEWWebiny documentation
Home Page: https://docs.webiny.com/
Webiny documentation
Home Page: https://docs.webiny.com/
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)
Double check to see if SecureRoute and SecureView are both necessary.
Update summary:
Remove
form-editor-field-group
form-editor-field-type
headers
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.
adding-security:
Adding Security title potentially renamed to 'Adding Protection to Menu' (or something similar)
This should include:
How to use cli-scaffold to develop new graphql services
How to use scaffolding
What it generates.
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.
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.)
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.
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.
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.
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.
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.
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.
Not at the moment.
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.
Remove sub-headers from Summary
security-scopes-list
secure-route-error
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.
Setup webiny-js
repo - this is where Webiny is located. You're gonna want to read the Contributing document.
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.
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:
The answer is the @webiny/app-admin
package (located in packages/app-admin
), some examples can be found here:
packages/app-admin/src/plugins/GlobalSearch/index.tsx
packages/app-admin/src/plugins/Logo/index.tsx
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
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
.
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.
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.
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 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.
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.
Translation is WIP
Roadmap is blocked by that task.
Update:
'apps/site/src/plugins/index.js' with proper app template
Update Summary:
Change Summary so it doesn't include refs to:
graphql-schema
graphql-context
graphql-context is now context
Replace GraphQLContext -> Context
Summary should not have the links to the functions at the top.
remove:
header-left
header-middle
header-right
menu
route
Task roadmap
Setup webiny-js
repo - this is where Webiny is located. You're gonna want to read the Contributing document.
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.
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:
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.
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.
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:
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.
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).
With shown components, the app also offers hasScopes
and hasRoles
helper functions. Might be useful when coding non-React logic.
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:
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.
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.
Remove this article
-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.
Roadmap:
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
When running deploy-apps
, the desired environment config may be missing:
webiny deploy-api --debug --env={env}
Update layout-internals:
Example needs to be converted to typescript
Under Tools used:
Serverless Components needs to be replaced (with a reason, perhaps another link) on the new method and motivation for doing so.
replace ~@webiny/app-page-builder-theme/src/styles.scss
with ~@webiny/app-page-builder-theme/styles.scss
Roadmap for this menu:
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.
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.'
Image needs to change to this
Remove use of roles in example
We can selectively deploy components using --alias=xyz
parameter(s). Add a note to Development principles
mentioning this parameter.
Update registering-a-theme:
Update paths for apps/site/src/plugins/index.ts
Example and explanation needs to be updated with react-app-template
Update Security Service Architecture Graph: Diagram
Regarding usage of Personal Access Token validation (PAT)
Look for reference in Form Builder
The motivation here is that Guides, FAQ, and How To Contribute need to be more visible to the end-user.
Check code example regarding MenuRenderComponent
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
We need to explain what webiny.root.js
and webiny.config.js
do and how to configure them
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/"
update button-element:
Replace anything with "webiny-cms"
to "webiny-pb"
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
.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.