v3@alpha.12 - GraphQL, Rich Text Editor & Redesigned Dashboard 🎉

GraphQL, Rich Text Editor & Redesigned Dashboard are released on npm!

🚀 GraphQL

Requesting a REST API can quickly become complex especially if you have to deal with relations. Furthermore, even though the client only needs few fields, REST APIs send every single property of each entity. This involves important performance issues, in particular for mobile applications used with low-speed networks.

For these reasons, in 2015, Facebook published GraphQL: a brand new query language for APIs.

Over the last past two years, GraphQL has been growing at a vertiginous speed. Giant companies like Yelp, Spotify, Github, Walmart and NYTimes already published a GraphQL API. The trend on Google speaks for itself:

Implementation

As you probably know, APIs generated with Strapi are, by default, REST APIs. The idea with this plugin was to add a new layer to easily request the API using GraphQL, without breaking the existing endpoints.

To implement GraphQL, we created a new plugin named graphql which creates a new endpoint /graphql and the GraphiQL interface.

Permissions

In a Strapi project, API security rules can easily be managed thanks to the Users & Permissions plugin. It works as well with GraphQL. The rules (also named policies) are associated to a controller's action. When you're making a query with GraphQL, you're hitting the same controller's actions as you were doing with the REST endpoints.

Let's take an example, the GET /post endpoint call the same logic than the following GraphQL Query:

1query {
2  posts {
3    title
4    content
5  }
6}

Both will execute the find action in the Post.js controller.

1// Post.js
2module.exports = {
3
4  find: async (ctx) => {
5    return strapi.services.post.fetchAll(ctx.query);
6  },
7
8  ...
9}

It makes our permissions layer compatible with the REST endpoint and the GraphQL query as well.

By default, the GraphQL queries are secured, you need to be authenticated by sending the Authorization header with the request see the React-Apollo example. Otherwise, you can make the queries available to everyone or allow the access using the administration panel (Users & Permissions > Roles > Public > Application).

Usage

To get started with GraphQL in your app, please install the plugin first. To do that, open your terminal and run the following command:

1strapi install graphql

Then, start your app and open your browser at http://localhost:1337/graphiql. You should see the interface (GraphiQL) that will help you to write GraphQL queries to explore your data.

Configurations

By default, the Shadow CRUD feature is enabled and the GraphQL is set to /graphql. You can edit these configurations in the following file.

Path — ./plugins/graphql/config/settings.json.

1{
2  "endpoint": "/graphql",
3  "shadowCRUD": true
4}

Query API

In the section, we assume that the Shadow CRUD feature is enabled. For each model, the plugin auto-generates queries which just fit your needs.

Fetch a single entry

• id: String

1query {
2  user(id: "5aafe871ad624b7380d7a224") {
3    username
4    email
5  }
6}

Fetch multiple entries

1query {
2  users {
3    username
4    email
5  }
6}

Filters

You can also apply different parameters to create more complex queries.

• limit (integer): Define the number of returned entries.
• start (integer): Define the number of entries to skip.
• sort (string): Define how the data should be sorted.
• where (object): Define the filters to apply in the query.
  • <field>: Equals.
  • <field>_ne: Not equals.
  • <field>_lt: Lower than.
  • <field>_lte: Lower than or equal to.
  • <field>_gt: Greater than.
  • <field>_gte: Lower than or equal to.
  • <field>_contains: Contains.
  • <field>_containss: Contains sensitive.

Return the second decade of users which have an email that contains @strapi.io ordered by username.

1query {
2  users(limit: 10, start: 10, sort: "username:asc", where: {
3    email_contains: "@strapi.io"
4  }) {
5    username
6    email
7  }
8}

Return the users which have been created after the March, 19th 2018 4:21 pm.

1query {
2  users(where: {
3    createdAt_gt: "2018-03-19 16:21:07.161Z"
4  }) {
5    username
6    email
7  }
8}

Shadow CRUD

To simplify and automate the build of the GraphQL schema, we introduced the Shadow CRUD feature. It automatically generates the type definition, queries and resolvers based on your models. The feature also lets you make a complex query with many arguments such as limit, sort, start and where.

Example

If you've generated an API called Post using the CLI strapi generate:api post or the administration panel, your model looks like this:

Path — ./api/post/models/Post.settings.json.

1{
2  "connection": "default",
3  "options": {
4    "timestamps": true
5  },
6  "attributes": {
7    "title": {
8      "type": "string"
9    }
10    "content": {
11      "type": "text"
12    },
13    "published": {
14      "type": "boolean"
15    }
16  }
17}

The generated GraphQL type and queries will be:

1type Post {
2  _id: String
3  created_at: String
4  updated_at: String
5  title: String
6  content: String
7  published: Boolean
8}
9
10type Query {
11  posts(sort: String, limit: Int, start: Int, where: JSON): [Post]
12  post(id: String!): Post
13}

The query will use the generated controller's actions as resolvers. It means that the posts query will execute the Post.find action and the post query will use the Post.findOne action.

Go further

Of course, you can fully customise the GraphQL schema: take a look at the documentation to add new types, execute policies before a resolver, link a query to a controller action, define a custom resolver, apply permissions on a query, disable (or depreciate) a query/type, etc.

Want to give it a try with React? Check out the example app using React & Apollo.

This version only supports queries. Mutations and subscriptions will be released in the next few months. That being said, pull requests are welcomed.

🚀 Rich Text Editor

If you use Strapi to manage content, you probably need to edit blocks of text through a Rich Text Editor.

With more than 240 votes on the Vote page, the commonly called "WYSIWYG" (What You See Is What You Get) editor, jumped on the top of our priorities.

Markdown syntax

Two syntaxes are commonly used by Rich Text Editors: HTML and Markdown.

HTML is the well-known language which powered every single page on the web. It is undeniably the most powerful way to write rich content, but the syntax may sometimes look heavy for basic stuff.

A great alternative is Markdown: a lightweight markup language with plain text formatting syntax, which can be easily converted into HTML. This language is trusted by many editors, CMS and companies, like GitHub. Since it is more lightweight than HTML (but can still contain HTML for section requiring a specific format) we chose it for the brand new Rich Text Editor.

The text is stored in the database as Markdown and exposed by your Strapi API in the same format. We advise you to use a node module such as Showdown to convert it into HTML in your frontend.

Draft

Since we had specific requirements and will add features in the future, the Rich Text Editor had to be entirely customizable. We benchmarked many existing open source WYSIWYG editors and finally went for Draft to create our own.

Draft is a Rich Text Editor framework for React. Its main advantage is the level of customization it offers. It has been built as a framework instead of a heavy editor, it lets developers add very specific behaviours.

Upload

Content Management is not only about text, but also about media.

Any content block may include assets, such as images or videos. Because file upload is already handled by Strapi, we used it to extend the capabilities of this new WYSIWYG. Files can be added with a simple drag and drop, browsing or pasting.

Preview & full-screen mode

Editing is necessary. Previewing is handy.

Markdown is an easy to learn syntax. The only trouble is that you need to preview what you are writing. Don't worry, we added an easy to use preview mode, so you can see what your content actually looks like.

Bonus! We added a full-screen mode to let you comfortably edit content.

🚀 New Dashboard Design

Last but not least, we entirely reviewed the design of the home page of the dashboard. From now, it looks much better and several useful informations are displayed through three sections.

Welcome section

The new homepage becomes much more welcoming: keep an eye on the latest article published in our blog, easily jump into the documentation and discover how to use Strapi thanks to existing code examples.

Community links section

Community drives and will always drive Strapi. We added some links to let you easily find us on GitHub, Slack, Medium, Twitter, Reddit and Stack Overflow.

We also added a simple form which let you subscribe to the newsletter, so you can easily get notified about the hottest Strapi news (releases, etc.).

Support us section

Strapi is an open source project which requires a lot of maintenance time. Day after day we do our best make API development more straightforward.

In the future, this page will be fully extensible so you will be able to see custom blocks displayed according to your needs and the plugins you installed.

Improvements

Many bugs have been fixed and a strong list of enhancements have been added. Take a look at the release note on GitHub to know more.

Thank you so much lucaperret, TheWebsDoor, Froelund, Jan10, declantyson, Makeyko and cece95 for your contributions!

Give it a try!

Looking forward to trying this new version?

Requirements:

• Node 9 installed on your machine.
• MongodDB installed and running.

Install it:

1$ npm i strapi@alpha -g

Check installation:

1$ strapi -v

This should print 3.0.0-alpha.12.

Create your first project:

1$ strapi new my-app

Choose your database credentials (we strongly recommend you to use MongoDB).

Start your server:

1$ cd my-app
2$ strapi start

Open the admin panel, start building your API, give a look at the documentation to discover the next steps and join us on Slack to give your feedback.

What is coming next?

Many of you have been complaining about the lack of stability. You are right: some parts of Strapi are buggy. But don't worry!

Stability over functionalities.

Adding more features is good, but solid foundations are better. During the next few weeks, we are going to make Strapi much more stable and easier to use.

96 issues are currently open on GitHub. The most critical issues are going to be fixed in the next few weeks. Take a look at the milestones to know more.

Deploying Strapi to production is still tricky because of the data migration. Settings and security rules (permissions) are stored in the database. It is handy when we are developing. But when it comes to production, you have to migrate your data from the development to the production environment, what is currently a pain. We already started thinking about solutions to automate data migration between environments (please add your suggestions to the corresponding GitHub issue).

The contribution workflow is going to be simplified to let you improve Strapi as easily possible. To do so, the development process will be more precisely documented and the setup time is going to be drastically reduced (including thanks to Webpack 4 update).

Happy with these updates? Share the article to spread the word around you!

Stay tuned!