Simply copy and paste the following command line in your terminal to create your first Strapi project.

Get Started

Strapi is one of the best CMS’s out there. There are many options for deploying to choose from such [AWS](https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.html) or [DigitalOcean](https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/digitalocean.html), [Azure](https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.html), [Google App Engine](https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/google-app-engine.html) or [render](https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/render.html). However, these are not that trivial for someone who is not experienced in DevOps. I will walk you through how to install your Strapi instance in Heroku.


## What is Heroku?

*Heroku* is a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud. 
It supports several languages such as Java, Nodejs, Go, PHP, Python. Strapi is a Nodejs application!

**What We Need**

To get started, we will need to have the following in place:

- [Github Account](https://www.github.com)
- [Heroku Account](http://heroku.com)
- [Git](https://git-scm.com/) Installed on your machine
- Nodejs  v14+ installed 
- Code Editor (I use VScode)

**Goal**

At the end of this guide, you should be able to:

- Install Strapi Locally
- Push your Strapi codebase to Github
- Connect your Heroku account to your Github(the project repository) and enable [Automatic Deploy](https://devcenter.heroku.com/articles/github-integration#automatic-deploys)
- Connect your Strapi project to Postgres add-on database provided by Heroku.


**Installing Strapi Locally**

To install Strapi, run this on your machine:

```bash
    npx create-strapi-app my-project --quickstart
```

This will create a folder called my-project and automatically install Strapi. After that, you should be able to access  http://localhost:1337/admin . Opening this for the first time will redirect you to http://localhost:1337/admin/auth/register-admin . This is because we have no super admin yet in the database. By default, Strapi uses SQLite as a file-based database.


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634691450280_admin.png)




![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634693677861_dashboard.png)


You need to create your first super admin locally. I want you to know that Heroku does not completely support SQLite. Read more about [SQLite support](https://devcenter.heroku.com/articles/sqlite3). So it is important to understand that the super admin you will be creating locally will differ from the one that you will create when you host on Heroku. And of course, you need to have a super admin locally because that is how you will be able to create a new collection type schema as Strapi does not allow that to be done in production.

**Create a Repository and Pushing to Github**

Heroku has a Command Line Interface (CLI) that can be used to push your code directly to its platform. However, using GitHub to version control your codebase is more organised.

So you need to create a git repository on GitHub and run the following command in the root of your Strapi instance.

```
    git init
    git add .
    git commit -m "first commit"
    git branch -M main
    git remote add origin https://github.com/USERNAME/NAMEOFREPOSITORY.git
    git push -u origin main
```

Where `USERNAME` is your GitHub username and `NAMEOFREPOSITORY` is the name given to your just created repository.


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638454195232_2021-12-02_15-09.png)


**Connecting to Heroku**

For Heroku to have access to your GitHub code, it is important that you log in to your GitHub account in the same browser that your Heroku account is logged in.

Your Heroku dashboard should look like so if you do not have an existing application:


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634694682510_create.png)


Click on **Create new app**.

Input your app name (Heroku will tell you if the name is available).

Then click on **Create app**.


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634695004682_name.png)



Choose GitHub as the **Deployment Method**

Then search the repository you wanted to  deploy.


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634695185681_git.png)


**Enable Automatic Deploys:** 

What this does is that whenever you push new changes from the local laptop to your GitHub, these changes will be deployed automatically on Heroku. 

Then Deploy.

![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634695307104_deplyyyy.png)


This is going to take a while to deploy and build(usually less than 2 minutes). Afterward, you can view you application by clicking **View**


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634696217281_runnung.png)


You have successfully deployed your Strapi application on Heroku. That is not all. Remember what I said about SQLite database not being supported by Heroku. Creating a new super admin in the Heroku instance with connecting to another database will always wipe off your data every 24 hours and this is not good. To fix this, we are going to be using the PostgreSQL Database provided by Heroku add-on (you can use any services you which).


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1634720294485_addon.png)


**Using Heroku Postgres Addon as Database**

The default Sqlite database Strapi ships with is not production-ready, If you are deploying to Heroku, chances are that  you would not want you data to keeps deleting every time your dyno sleeps, So  we will be using Postgres database that is provided by Heroku. 

To do that, on your app created on Heroku, go to the **Resources** tab.
Search for Heroku Postgres on the **Add-ons** sections.


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638455166728_postgres.png)

Click on Heroku Postgres, you should get this:


![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638455206115_2021-12-02_15-26.png)


Click on **Submit Order Form**

Now, go to the Settings tab.

![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638455279860_headback.png)



![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638455370171_reveal.png)


Clicking **Reveal Config Vars**  will only display  **DATABASE_URL** with its long value. This is how the full syntax should look like:

 **postgres://{user}:{password}@{hostname}:{port}/{database-name}**
  

![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638594441247_dbsecret.png)



**Adding Environment Variables to Strapi**

Your default local development database configuration can be found in your Strapi project at **./config/database.js**


 Create subfolders **env→production** with **database.js**  inside **config**, then add  the following code inside the newly created **env/production/database.js**
 
```
    const parse = require('pg-connection-string').parse;
    const config = parse(process.env.DATABASE_URL);
    module.exports = ({ env }) => ({
      connection: {
        client: 'postgres',
        connection: {
          host: config.host,
          port: config.port,
          database: config.database,
          user: config.user,
          password: config.password,
          ssl: {
            rejectUnauthorized: false
          },
        },
        debug: false,
      },
    });
```

Notice that we are using a [**pg-connection**](https://yarnpkg.com/package/pg-connection-string) package here. This contains functions for dealing with a PostgresSQL connection string. This is because we do not want to assign too many environment variables. We need to install this package.

Run this:

```bash
    yarn add pg-connection-string 
```

and also install Postgres client as well: 

```
    yarn add pg
```

**It is important that you use yarn to install the above packages instead of npm else it will fail during build time.**

Now, add, commit, and push your code to Github, and since your Heroku app is linked to the repository, it will take less than 2 minutes to build and everything should start working. if you add **/admin** to the hosted Strapi URL, it will prompt you to add a super admin, but this time, it will be saved in the Postgres database and will not delete when the [dyno](https://www.heroku.com/dynos) sleeps(If you are on the free dyno type)



![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638596381633_prod.png)




![](https://paper-attachments.dropbox.com/s_7915735F1CAB252A6C04BE6B30397665DEF2AFEC11D1051D0C16B6CF3C5E81A8_1638596791513_register.png)



## Conclusion

Congratulations, you have seen it to the end of this guide. You have seen how to install Strapi locally and deploy on Heroku, we even went ahead to use an add-on Postgres database provided by Heroku.



The Tutorials section covers an introduction to Strapi, some advanced technical content, product updates and releases. From basic workaround to in-depth development guides. 

Tutorials

medium_Integration _ Heroku.png

small_Integration _ Heroku.png

thumbnail_Integration _ Heroku.png

Integration _ Heroku.png

The article has been updated with Strapi v4 by Precious Luke  

The Product section covers our releases, feature reviews and more. 

Product

The Ecosystem section covers everything related to the world of Headless CMS and Strapi's place in it. 

Ecosystem

The latest Strapi-related news and major events happening for Strapi – including announcements, remote-work, organization and tips on running a start-up. 

Company

Get all the latest updates, news and events.

Subscribe to the newsletter 📣

Strapi v4 is here! Learn all the steps you need to take to migrate your plugin with as little friction as possible. We've also included some codemods, or code that modifies your code automatically.

Strapi Guided Tour-5.png

v4 Plugin Migration Guide

The Big 4, the Fantastic 4... How about Strapi v4? Meet a brand new version of Strapi: a more powerful CMS coming wrapped in a new dazzling design. Have a look at what's new!

strapiv4_blog_cover (1) (1).png

Announcing Strapi v4

The Strapi UI Kit allows everyone to easily create the UI for a plugin or admin panel customisation, using Strapi design guidelines and ready-made components. Just duplicate the Figma file and get the creativity going! 

strapi design system

Introducing the Strapi UI Kit

💡*Please note, that we have released an updated plugin migration guide. We suggest following the [migration guide](https://docs.strapi.io/developer-docs/latest/update-migration-guides/migration-guides/v4/plugin-migration.html) in the Strapi documentation.*

Strapi v4 is here! This is a major release packing a lot of amazing new features. Unfortunately, this does mean that there will be some breaking changes when moving from v3 to v4. Since the new Plugin API is a big part of Strapi v4, we decided to put together a migration guide for plugin developers.

Here you will find all the steps you need to take to migrate your plugin with as little friction as possible. To expedite the process we've also included some codemods, or code that modifies your code automatically.

The goal of this guide is to get a v3 plugin up and running on v4 as fast as possible by resolving breaking changes. It is not an exhaustive resource for the v4 plugin API. For more information, you should consult the v4 plugin API documentation: [Server API](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/server.html#server-api-for-plugins), [Admin API](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.html#admin-panel-api-for-plugins)

When possible, this guide suggests the use of codemods. To use the codemods you will need to clone this repository and run all commands provided from its root:

```bash
git clone https://github.com/strapi/codemods.git
```

# 1. Enable your plugin

A v3 plugin was enabled if it was installed or it was found in the `plugins` directory. In v4, if a plugin is installed (in the `package.json` dependencies), it is automatically enabled. However, while developing a local plugin you must explicitly enable the plugin in the `./config/plugins.js` file of the Strapi application. Disabling any plugin and adding additional config can be done here as well. Here's an example for a local plugin:

```jsx
module.exports = ({ env }) => ({
  "my-plugin": {
    enabled: true,
    resolve: "./my-local-plugin",
    config: {
      // additional config goes here
    },
  },
});
```

# 2. Update the folder structure

As opposed to v3 plugins, which required a specific folder structure, v4 plugins are developed using a programmatic API.

At the root of your plugin you must have the `strapi-server.js` and `strapi-admin.js` entry files. Otherwise, the folder structure is up to you. Here is an example:

```jsx
/plugin
-- /admin
---- /components
---- /pages
---- // etc...
---- index.js
-- /server
---- /config
---- /controllers
---- /routes
---- bootstrap.js
---- // etc...
---- index.js
-- strapi-server.js // require('./server')
-- strapi-admin.js // require('./admin')
```

**Migrate with codemod**

To make this update, you can use the following codemod to move files and folders into a v4 plugin structure:

```jsx
node ./migration-helpers/update-plugin-folder-structure.js <path-to-v3-plugin> [path-for-v4-plugin]
```

> ℹ️ This codemod will create a new v4 plugin leaving your v3 plugin in place. We recommend confirming the v4 version of your plugin is working properly before deleting the v3 version.

The codemod creates the two entry files `strapi-server.js` and `strapi-admin.js`, organizes files and folders into `/server` and `/admin` directories respectively, changes `models` to `contentTypes` , and exports `services` as functions.

> ℹ️ For a more detailed explanation of what the codemod does, consult the check list below

**Migrate by hand**

If you prefer to make these changes yourself, you can use the checklist below to help migrate your plugin.

> 💡 This is only a suggested folder structure. You can organize the plugin however you want as long as everything is imported to `strapi-admin.js` and `strapi-server.js`

- Create a `server` directory

**Controllers, services, and middlewares**

- Move `controllers`, `services` , and `middlewares` to `/server` . For each directory add an `index.js` file that exports all files in that folder. Make sure that each file in these directories exports a function taking `{strapi}` as a parameter and returns an object. For example the `controllers` directory would look like this:

```jsx
// server/controllers/my-controllerA

module.exports = ({ strapi }) => ({
  doSomething(ctx) {
    ctx.body = { message: "HelloWorld" };
  },
});
```

```jsx
// server/controllers/index.js

"use strict";

const myControllerA = require("./my-controllerA");
const myControllerB = require("./my-controllerB");

module.exports = {
  myControllerA,
  myControllerB,
};
```

**Bootstrap Function**

- Move bootstrap from `/server/config/functions/bootstrap.js` to `/server/bootstrap.js` and pass `{strapi}` as an argument:

```jsx
// server/bootstrap.js
"use strict";

module.exports = ({ strapi }) => ({
  // bootstrap!
});
```

**Routes**

- Move routes from `/config/routes.json` to `/server/routes/index.json`. Your routes should return an array or an object specifying `admin` or `content-api` routes.
- Make sure your routes handler matches the same casing of your controller exports

```jsx
// server/controllers/index.js

"use strict";

const myControllerA = require("./my-controllerA");
const myControllerB = require("./my-controllerB");

module.exports = {
  myControllerA,
  myControllerB,
};
```

```jsx
// server/routes/index.js

module.exports = [
  {
    method: "GET",
    path: "/my-controller-a/",
    // Camel case handler to match export in server/controllers/index.js
    handler: "myControllerA.index",
    config: { policies: [] },
  },
];
```

**Policies**

- Move policies from `/config/policies` to `/server/policies/<policyName>.js`, add an `index.js` file to the directory that exports all files in the folder.

**Models / Content-Types**

- Move / rename the `models` directory to `/server/content-types`

  - Move / rename each model's `<modelName>.settings.json` to `/server/content-types/<contentTypeName>/schema.json`

    - Update the info object on each `schema.json`

    ```json
    "info": {
      "singularName": "content-type-name", // kebab-case required
      "pluralName": "content-type-names", // kebab-case required
      "displayName": "Content-Type Name",
      "name": "Content-Type Name",
    };
    ```

    - If your model used lifecycle-hooks found in `<model-name>.js` move / rename this file `/server/content-types/<contentTypeName>/lifecycle.js`, otherwise delete the file.
    - Create an index file for each Content Type that exports the schema and lifecycles

    ```jsx
    // server/content-types/<content-type-name>/index.js

    const schema = require("./schema.json");
    const lifecycles = require("./lifecycles.js");

    module.exports = {
      schema,
      lifecycles,
    };
    ```

    - Create an index file for `server/content-types` and export all content-types
    - Make sure the key for your Content-Types matches the singular name on the Content-Type’s schema.json info object.

    ```json
    // server/content-types/content-type-a/schema.json

    "info": {
      "singularName": "content-type-a", // kebab-case required
      "pluralName": "content-type-as", // kebab-case required
      "displayName": "Content-Type A",
      "name": "Content-Type A",
    };
    ```

    ```jsx
    // server/content-types/index.js
    "use strict";

    const contentTypeA = require("./content-type-a");
    const contentTypeB = require("./content-type-b");

    module.exports = {
      "content-type-a": contentTypeA,
      "content-type-b": contentTypeB,
    };
    ```

**Entry Files**

- Create the server entry file at the root of your plugin: `strapi-server.js` and require all necessary files for your plugin. For example:

```jsx
// strapi-server.js
"use strict";

const bootstrap = require("./server/bootstrap");
const contentTypes = require("./server/contentTypes");
const controllers = require("./server/contentTypes");
const services = require("./server/services");
const routes = require("./server/routes");

module.exports = {
  bootstrap,
  contentTypes,
  controllers,
  services,
  routes,
};
```

- Create the frontend entry file at the root of your project: `strapi-admin.js` For example:

```jsx
// strapi-admin.js
"use strict";

module.exports = require("./admin/src").default;
```

# 3. Migrate the Back End

## Update imports

Strapi has now moved to scoped imports. All Strapi imports will need to be updated from `strapi-package-name` to `@strapi/package-name`.

**Migrate with codemod**

To update your `package.json` you can use the following codemod:

```jsx
node ./migration-helpers/update-package-dependencies.js <path-to-plugin>
```

> ⚠️ This will modify your plugin source code. Before running this command, be sure you have initialized a git repo, the working tree is clean, you've pushed your v3 plugin, and you are on a new branch.

To update any files importing Strapi packages you can run:

```jsx
npx jscodeshift -t ./transforms/update-scoped-imports.js <path-to-file | path-to-folder>
```

> ⚠️ This will modify your plugin source code. Before running this command, be sure you have initialized a git repo, the working tree is clean, you've pushed your plugin to GitHub, and you are on a new branch.

**Migrate by hand**

If you prefer to make this change yourself, you just need to find any imports of Strapi packages and rename them to `@strapi/package-name`

## Update Models to Content-Types

### Update Getters

If your plugin has models (contentTypes) you will need to make the following changes.

Models are now called ContentTypes. All getters like `strapi.models` will need to be updated to `strapi.contentTypes`

**Migrate with codemod**

You can use the following codemod to replace all instances of `strapi.models` with `strapi.contentTypes`

```jsx
npx jscodeshift -t ./transforms/change-model-getters-to-content-types.js <path-to-file | path-to-folder>
```

> ⚠️ This will modify your plugin source code. Before running this command, be sure you have initialized a git repo, the working tree is clean, you've pushed your plugin to GitHub, and you are on a new branch.

**Migrate by hand**

If you prefer to do this yourself, you just need to replace any instance of `.models` with `.contentTypes`

> 💡 To refactor further, check out the [new getters](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/server.html#usage) introduced in the Strapi v4 Plugin API

### Update relations

If your plugin has contentTypes with relations, those attributes will have to be updated manually depending on the relation. Here's an example of all possible relations between an `article` and an `author`

```json
// article attributes
"articleHasOneAuthor": {
  "type": "relation",
  "relation": "oneToOne",
  "target": "api::author.author"
},
"articleHasAndBelongsToOneAuthor": {
  "type": "relation",
  "relation": "oneToOne",
  "target": "api::author.author",
  "inversedBy": "article"
},
"articleBelongsToManyAuthors": {
  "type": "relation",
  "relation": "oneToMany",
  "target": "api::author.author",
  "mappedBy": "article"
},
"authorHasManyArticles": {
  "type": "relation",
  "relation": "manyToOne",
  "target": "api::author.author",
  "inversedBy": "articles"
},
"articlesHasAndBelongsToManyAuthors": {
  "type": "relation",
  "relation": "manyToMany",
  "target": "api::author.author",
  "inversedBy": "articles"
},
"articleHasManyAuthors": {
  "type": "relation",
  "relation": "oneToMany",
  "target": "api::author.author"
}

// author attributes
"article": {
  "type": "relation",
  "relation": "manyToOne",
  "target": "api::article.article",
  "inversedBy": "articleBelongsToManyAuthors"
},
"articles": {
  "type": "relation",
  "relation": "manyToMany",
  "target": "api::article.article",
  "inversedBy": "articlesHasAndBelongsToManyAuthors"
}
```

## Update configuration

If you have any default configuration it should be exported as an object on the [`config` property](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/server.html#configuration). This object expects a `default` property storing the default plugin configuration, and a `validator` function that takes the `config` as an argument. For example:

```jsx
// strapi-server.js

module.exports = () => {
// ...bootstrap, routes, controllers, etc...
config: {
    default: { optionA: true },
    validator: (config) => {
      if (typeof config.optionA !== 'boolean') {
        throw new Error('optionA has to be a boolean');
      }
    },
  },
}
```

# 4. Migrate the Front End

## Register the plugin

A v3 plugin exports its configurations as an object passed to `registerPlugin(config)`, like this:

```jsx
export default (strapi) => {
  const pluginDescription =
    pluginPkg.strapi.description || pluginPkg.description;
  const icon = pluginPkg.strapi.icon;
  const name = pluginPkg.strapi.name;
  const plugin = {
    blockerComponent: null,
    blockerComponentProps: {},
    description: pluginDescription,
    icon,
    id: pluginId,
    initializer: Initializer,
    injectedComponents: [],
    isReady: false,
    isRequired: pluginPkg.strapi.required || false,
    layout: null,
    lifecycles,
    mainComponent: App,
    name,
    pluginLogo,
    preventComponentRendering: false,
    reducers,
    trads,
    menu: {
      pluginsSectionLinks: [
        {
          destination: `/plugins/${pluginId}`,
          icon,
          label: {
            id: `${pluginId}.plugin.name`,
            defaultMessage: "My Plugin",
          },
          name,
          permissions: pluginPermissions.main,
        },
      ],
    },
  };

  return strapi.registerPlugin(plugin);
};
```

To migrate this to v4 we will need to export a function that calls the [`register()` lifecycle function](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.html#register), passing the current strapi app as an argument:

```jsx
export default {
  register(app) {
    // executes as soon as the plugin is loaded
  },
};
```

Here we can go ahead and register our plugin by grabbing the `name` and `id` keys from the old configuration object:

```jsx
import pluginId from './pluginId';

const pluginDescription = pluginPkg.strapi.description || pluginPkg.description;
const name = pluginPkg.strapi.name;

export default {
  register(app) {
      app.registerPlugin({
        id: pluginId
        name,
      })
    }
  }
```

## Add Menu Link

To add a link to your plugin in the Strapi Admin, use the [`addMenuLink()` function](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.html#menu-api) called in the `register` lifecycle. The `menu` key from the v3 config object can be passed to `app.addMenuLink()` with the following properties changed:

- `destination` ⇒ `to`
- `label` ⇒ `intlLabel`
- `icon` is no longer a string, it's now a React component. You can create it in a separate file like this:

```jsx
import React from "react";
import { Icon } from "@strapi/parts/Icon";
import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";

const PluginIcon = () => (
  <Icon as={() => <FontAwesomeIcon icon="paint-brush" />} width="16px" />
);

export default PluginIcon;
```

In v3 the component would be specified on the `mainComponent` key, in v4 the component is passed as a dynamic import to the `app.addMenuLink()` function.

```jsx
import pluginId from './pluginId';
import pluginPermissions from './permissions';
import PluginIcon from './PluginIcon'

const pluginDescription = pluginPkg.strapi.description || pluginPkg.description;
const name = pluginPkg.strapi.name;

export default {
  register(app) {
    app.addMenuLink({
      to: `/plugins/${pluginId}`,
      icon: PluginIcon,
      intlLabel: {
        id: `${pluginId}.plugin.name`,
        defaultMessage: 'My Plugin',
      },
      permissions: pluginPermissions.main,
      Component: async () => {
        const component = await import(/* webpackChunkName: "my-plugin-page" */ './pages/PluginPage');

        return component;
      },
    });

    app.registerPlugin({
      description: pluginDescription,
      icon,
      id: pluginId
      name
    });
  }
}
```

## Going Further

### All available actions

At this point a basic plugin with a single view should be migrated to v4. However, it is likely that you will want to customize your plugin further. Depending on the needs of your plugin you will have to look into the different API's available.

In addition to the [`register()` lifecycle function](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.html#register), which is executed as soon as the plugin is loaded, there is also the [`bootstrap()` lifecycle function](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.html#bootstrap) which executes after all plugins are loaded.

To add a settings link or section, use redux reducers, hook into other plugins, and modify the UI with injection zones, consult [this table](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.html#available-actions) for all available API's and their associated lifecycle functions.

### Register Translations

The plugin interface can also export an [asynchronous `registerTrads()` function](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.html#async-function) for registering translation files. You can use the following function:

```jsx
import { prefixPluginTranslations } from "@strapi/helper-plugin";

export default {
  register(app) {
    // register code...
  },
  bootstrap(app) {
    // bootstrap code...
  },
  async registerTrads({ locales }) {
    const importedTrads = await Promise.all(
      locales.map((locale) => {
        return import(
          /* webpackChunkName: "[pluginId]-[request]" */ `./translations/${locale}.json`
        )
          .then(({ default: data }) => {
            return {
              data: prefixPluginTranslations(data, pluginId),
              locale,
            };
          })
          .catch(() => {
            return {
              data: {},
              locale,
            };
          });
      })
    );

    return Promise.resolve(importedTrads);
  },
};
```

# Conclusion

Hopefully this guide has helped you migrate your plugin from Strapi v3 to Strapi v4. [Strapi Market](https://market.strapi.io/) is coming soon and we are looking forward to many plugins developed by the community. For more information about Strapi Market, read the [blog post](https://strapi.io/blog/strapi-market-is-coming-soon). If you are ready to submit your plugin all you need to do is fill out this [form](https://market.strapi.io/submit-plugin).

If you have any issues with the codemods or would like to contribute to the project please [create an issue](https://github.com/strapi/codemods/issues) or [open a pull request](https://github.com/strapi/codemods/pulls).


[We are live on Product Hunt!](https://www.producthunt.com/posts/strapi-0ea3c5eb-2b7c-4521-b51c-9b583f125665) Feel free to leave us a review 🙏

Last year, we introduced a stable Strapi v3 with the [role-based access control](https://strapi.io/features/custom-roles-and-permissions),[ draft and publish feature](https://strapi.io/blog/announcing-a-new-draft-and-publish-feature), [SSO authentication](https://strapi.io/blog/v3-5-sentry-plugin-sso-authentication), and most awaited [internationalization](https://strapi.io/blog/announcing-content-internationalization-v3-6). We reached [40 000+](https://github.com/strapi/strapi/)  Github stars. We held the first online global user conference [StrapiConf](https://conf.strapi.io/), with more than 2,500 live attendees. 

Most importantly, the Strapi community keeps growing in size and level of engagement. Thank you for every contribution, feedback, little gesture of help, and for building Strapi with us.

Since the release of the first version, we have been carefully listening to your feedback about the limitations you faced while using Strapi. Contributions were not smooth, migration from one version to another wasn't the best, plugins were sometimes hard to maintain, the API performance, format, and capabilities could be better. 

But not anymore.

## Introducing Strapi v4

We have deeply **reworked the Strapi core** to make it easier to extend Strapi with plugins, smoothly migrate from one version to another, and boost API performance. All that with a brand new user interface and design system. 

<iframe width="560" height="315" src="https://www.youtube.com/embed/qWKdF8N8LQU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

[Strapi v4](https://strapi.io/v4) allows everyone to easily extend Strapi through plugins and customize the admin panel as needed. The new version will also increase the velocity of new feature development by our team, which means we’ll be shipping updates more frequently.

Here’s what Kuldeep Arora, Principal Delivery Lead at [Virgin Media](https://www.virginmedia.com/), said about the new version:
*"Strapi v4 not only boosts performance compared to the previous version but also makes the process of integrating other tools in our stack a breeze”. *

Intrigued? Let's have a look at what's new.

## Meet the new look of your favorite CMS
More intuitive, more accessible, more aesthetic. 
We gave Strapi a complete makeover, improved the navigation and accessibility of the admin panel to make sure that it not only pleases the eye but also makes users more efficient. 

![strapi v4 screenshot.png](/uploads/strapi_v4_screenshot_5cb222faff.png)

## The brand new Strapi Design System

Along with the updated admin panel interface, we are releasing the first version of the [Strapi Design System](https://design-system.strapi.io/).

Our goal is to allow everyone to **extend and customize their Strapi applications with plugins**. To ensure design consistency and provide the best experience to Strapi users, we created a component library that plugin developers can use for the interface of their plugin.

![components.png](/uploads/components_a32c1d133a.png)

We took the time to select the right colors, pay attention to the contrast ratio, create elements with adaptive size and make sure all pieces of the Strapi interface were consistent. This way, no matter what plugins are added to an application, users will always have a pleasant experience, and nothing will interfere with their productivity and creativity.

We have also created a [Strapi UI Kit](https://strapi.io/blog/introducing-strapi-ui-kit) available on Figma: just duplicate the file and get started with the design! 

Have a look at what's new: 
<iframe width="560" height="315" src="https://www.youtube.com/embed/cKc082C2gzY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Plugin API: create plugins in a breeze

Our vision is to enable everyone to extend their Strapi application, customize and integrate it with other tools. We want to scale the Strapi ecosystem to let users choose among a big variety of high-quality plugins and to let plugin creators showcase their work. To achieve it, in the v4 we are making the plugin creation and use as smooth as possible.

The new [Plugin API](https://docs.strapi.io/developer-docs/latest/developer-resources/plugin-api-reference/server.html) lets developers create plugins without pain. In Strapi v3, plugins were loaded based on a file structure. To create a plugin, one would need to configure many files.  This approach didn't provide code flexibility and made it difficult to maintain the plugin.

In the v4, we've moved to a programmatic approach, which means that plugins can have their own file structure. Plugin developers only need to configure two files at the root of the package:

-   ``strapi-server.js``  for the  ``Server``.

-   ``strapi-admin.js``  for the  ``Admin panel``.

In addition, they can use the components provided by the [Strapi Design System ](https://design-system.strapi.io/)to build the admin panel interface of their plugins effortlessly. This way, developers don't need to spend time on creating the plugin UI and focus only on feature development. These improvements make the plugin creation experience smoother and enable plugin developers to share their work with others, collaborate, and contribute more efficiently.

Strapi users will extend their applications by using the plugins created by other enthusiasts, saving days of work in the process. 

This is the foundation for a healthy ecosystem, and we can't wait to work with you on extending Strapi's capabilities and integrations with other tools.

Here are more details about the new Plugin API:
<iframe width="560" height="315" src="https://www.youtube.com/embed/-51iT5-eO9c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

The v3 plugins will not be compatible with the v4 and need to be migrated. We have prepared a detailed [tutorial](https://strapi.io/blog/v4-plugin-migration-guide) on how to migrate v3 plugins to v4. Naturally, the plugins created for the v4 will not be compatible with older Strapi versions.

If you have** already created or migrated a v4 plugin**, please [share it with us](https://strapi.io/strapi-market-guidelines) to be featured on the future Strapi Marketplace 

## A powerful database query engine
This significant improvement allows developers to efficiently interact with the database, have more control of the data, fetch it in a smarter way, and custom code more easily.

We have **improved the way queries to the database are done**: you can now select which fields and relations you're going to load from the database, make complex queries on components, filter and sort data like a pro. We have also added the OR, AND & NOT operators and filtering on components. It means that you will get only the data you need instead of ALL data, which improves the performance of your project.

With this database layer, **developing new features is so much easier.** The syntax used for this query system is intuitive and understandable, inspired by the ecosystem's best tools. It means that to customize Strapi, you will not need to spend time learning overcomplicated systems.

![database_query_engine_v4.png](/uploads/database_query_engine_v4_e23431f445.png)

With the new database query engine, we will also be able to ship features faster, such as the awaited versioning, preview, activity logs, better cross-environment migration, and more (by the way, [let us know](https://portal.productboard.com/strapi/1-roadmap/tabs/2-under-consideration) what features you'd love to see in the next versions!)

Have a look at [more details](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.html) about the new query engine and the database layer.

Also, check out this short video explaining the new query engine: 

<iframe width="560" height="315" src="https://www.youtube.com/embed/fGUxQ-v6qOQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## More powerful REST and GraphQL API

With a new database query engine under the hood, the REST and GraphQL API are becoming more advanced as well. 

**Get the precise data you need through the API** with the updated population and filtering systems and a possibility to load relations from the database. Since you can decide exactly what data to fetch via the API, it gives more space for creativity in frontend development. Focus on imagination and design without worrying about the backend constraints. The API will do all the job!

We added pagination to both APIs and standardized the request and response formats to ensure a more consistent experience. The split of attributes and meta allows you to expand and customize API.

![rest_api.png](/uploads/rest_api_07a176f9a0.png)

We have added new features to the content API, such as pagination, better filtering format, and the possibility to choose what relations to load. 

Have a look at the [REST API](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/rest-api.html) and [GraphQL API](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/graphql-api.html) documentation for more detail.

Check out the overview video to see the new API in action: 

<iframe width="560" height="315" src="https://www.youtube.com/embed/jOSh2nogROg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## API Token: quick and easy setup

In v4, we're introducing an important change in the API: the Content API and the Admin API are now separated, and the access to the Content API can be easily managed using the[ API Tokens.](https://docs.strapi.io/user-docs/latest/settings/managing-global-settings.html#managing-api-tokens)

The Content API users can now authenticate their queries (REST & GraphQL) with a token (Access key) administered from the admin panel. The tokens can be created in the settings of the app. They are permanent and can only be seen once when the admin creates them.

![Token type.png](/uploads/Token_type_8ae0306190.png)

Super admins can set up specific permissions to grant access to the API token settings section and CRUD actions on tokens. This feature lets Strapi users manage the permissions of the  Content API requests more smoothly. It also allows you to get started with Strapi faster with simple settings.

Have a look at the API Token feature demo: 

<iframe width="560" height="315" src="https://www.youtube.com/embed/1SlYKWMgeTE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Error Handling: deal with errors easily
We have standardized the error codes and added a meaning for each one of them. From now on, whenever you receive an error you’ll know what exactly it means and how to deal with it. Learn more about error handling [here]( https://docs.strapi.io/developer-docs/latest/developer-resources/error-handling.html). 

<iframe width="560" height="315" src="https://www.youtube.com/embed/LB6SFDKqeQc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Let’s celebrate Strapi v4 together!
We organised a festive edition of our monthly community call to celebrate this huge milestone together! We did the v4 to show what's new, answered all questions and took a moment to thank everyone for helping us in this journey.

Here's the replay of the v4 edition Community Call:

<iframe width="560" height="315" src="https://www.youtube.com/embed/Ge-dDLgafP8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

To unite local Strapi communities, we will also be organising **v4 release parties in different cities around the world**.
A v4 Release party is a 1-2 hour get-together to meet other developers in the Open Source community who are interested in learning more about the superpowers that come with Strapi v4.

Join us in organising a v4 release party in your local community. [Reach out to us](mailto:shada.wehbe@strapi.io) if you'd love to participate in the event organisation.

## Try Strapi v4 out now
To create a new Strapi v4 project, simply run the following command: 

``nnpx create-strapi-app@latest <my-project> --quickstart``

Follow the [Quick Start Guide](https://docs.strapi.io/developer-docs/latest/getting-started/quick-start.html) for detailed step-by-step instructions or have a look at a video instruction:

<iframe width="560" height="315" src="https://www.youtube.com/embed/h9vETeRiulY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Strapi v4 introduces a lot of breaking changes and we would love to hear what you think about it! Please share your feedback in this [forum thread](https://forum.strapi.io/t/strapi-v4-is-live/12940) and report any bugs you face on [Github](https://github.com/strapi/strapi/). 

## What happens to Strapi v3?

We will keep supporting v3 and fixing critical bugs for at least six months. However, we will stop delivering new features for v3, and we encourage you to use v4 for all new projects. The v3 documentation will still be available [here](https://docs-v3.strapi.io/).

The migration guide that will help you migrate from v3 to v4 is currently in progress, and we will share it once it's ready.

## Build Strapi with us

Strapi is an open-source product that grows thanks to community support and contributions.

Here's how you can help us improve the product:

-   Contribute to the project on [Github](https://github.com/strapi/strapi/blob/master/CONTRIBUTING.md)
-   [Submit your plugins](https://strapi.io/strapi-market-guidelines) to the Strapi Market (marketplace coming soon!)
-   Share what features you'd love to have in our [public roadmap](https://portal.productboard.com/strapi/1-roadmap/tabs/2-under-consideration)
-   Showcase the projects you built in the [Strapi Showcase](https://strapi.io/showcases) 

We appreciate each contribution and piece of feedback that you share. 
Stay tuned for more updates!

The Big 4, the Fantastic 4... How about Strapi v4? 
We're excited to introduce a brand new version of Strapi: a more powerful CMS coming wrapped in a new dazzling design. Intrigued? Have a look at what's new! 


[Strapi UI Kit](https://www.figma.com/community/file/1050701975985000987) is a design library of components based on Figma. It’s composed of buttons, modals, footers, headers, inputs, and other design elements. Everything has been made to follow contrast accessibilities and suit any need. 

This document is also the single source of truth for our team, which means you will always have the most up-to-date designs to play with. This file is free, so anyone can duplicate it, as long as you have a Figma account (they are free as well). 

## What's the purpose of the Strapi UI Kit? 

As an open company, we want to make sure our design components can be used by anyone and for any use case. We have already released a [technical component library](https://design-system-git-develop-strapijs.vercel.app/?path=/story/design-system-components-accordion--base), but we decided to go an extra-mile and decided to open-source not only our code, but also the design.

Internally we use this [UI kit](https://www.figma.com/community/file/1050701975985000987) as a single source of truth. All the components of this file are connected to their technical components via a [Storybook](https://design-system-git-develop-strapijs.vercel.app/) and have the same naming. The file is divided into 3 different pages: the design tokens, the components, and the premade pages that you can use as much as you want.

## How to use the UI Kit? 

The combination of the UI Kit, the [Strapi Design System](https://design-system.strapi.io/), and the [Plugin API](https://youtu.be/-51iT5-eO9c) makes magic. Contributing to Strapi, building your workarounds and creating plugins is now much easier. 

You can **create the interface of your plugin** or **customize the UI** of the Strapi admin panel in a blink of an eye, using ready-made components and design guidelines.

On top of the technical library, contributions are not restricted to developers and are open to anyone, be it developers, designers, product managers, or content creators.

Yet, the UI kit might not be exhaustive for all your different use cases. We tend to keep the UI kit as flexible as possible and introduce new components only if they have several potential applications.

[Any feedback is welcome](https://forum.strapi.io/t/design-system-libraries-components/13147), and we would be happy to address changes.

## What's next?

We'll iterate to make sure the contributors and creators have enough material to work and enhance Strapi. They are also welcome to contribute to the [Strapi Design System](https://design-system.strapi.io/).

## Join the v4 Plugin Creation & Migration stream

Today, at 5 PM CET / 8 AM PDT, join our team on Twitch to learn **how to create a v4 plugin** using the new Plugin API, UI Kit, and Design system. We will also explain **how to migrate your plugin from v3 to v4.**

[Register here](https://lu.ma/strapi-plugins) not to miss the event!

## Build Strapi with us

Strapi is an open-source product that grows thanks to community support and contributions.

Here's how you can help us improve the product:

- Contribute to the project on [Github](https://github.com/strapi/strapi/blob/master/CONTRIBUTING.md)

- Share what features you'd love to have in our [public roadmap](https://portal.productboard.com/strapi/1-roadmap/tabs/2-under-consideration)

- [Submit your plugins](https://strapi.io/strapi-market-guidelines) to the Strapi Market (marketplace coming soon!)

- Showcase the projects you built in [Strapi Showcase](https://strapi.io/showcases) 

We appreciate each contribution and piece of feedback that you share. Stay safe and tuned for more updates!

Last week, we announced the Strapi v4 stable release, along with the Strapi Design System, which enables everyone to easily customize the admin panel interface. To make UI customization even smoother, we're introducing the Strapi UI Kit.

Get all the latest Strapi updates, news and events.

Join our Newsletter

Deploying a Strapi API on Heroku in 5 min

pierre_burgy

Pierre created Strapi with Aurélien and Jim back in 2015. He's a strong believer in open-source, remote and people-first organizations. You can also find him regularly windsurfing or mountain-biking!