Strapi v5 Local Plugins Made Easy: A Guide to a Clean Monorepo Setup

local-plugin-in-strapi-v5

If you’ve ever tried to integrate a local plugin into your Strapi v5 project, you might have felt the frustration. You want to add a custom widget or extend the admin UI, and the docs just point you toward building a plugin. But what happens next? How do you manage this new plugin alongside your main Strapi application without a clunky, manual build process?

After scouring forums and finding more questions than answers, I pieced together a solution that’s surprisingly simple and elegant. Here’s how to tame your local plugins using a clean monorepo structure.

Part 1: Creating Your Local Plugin

First, let’s get the basic plugin running. Strapi’s documentation provides a solid starting point.

Scaffold a new Strapi app if you haven’t already.
Terminal window
```
npx create-strapi-app@latest my-project
```
Generate your plugin using the official SDK. This command creates a dedicated packages/my-local-plugin folder, which is a complete Node.js project in itself.
Terminal window
```
npx @strapi/sdk-plugin init packages/my-local-plugin
```
Register the plugin with your Strapi application. Create or edit config/plugins.ts to tell Strapi where to find it.
config/plugins.ts
```
1
export default {
2
  'my-local-plugin': {
3
    enabled: true,
4
    resolve: './packages/my-local-plugin',
5
  },
6
};
```

At this point, you can cd into packages/my-local-plugin and run npm run watch to auto-rebuild the plugin as you make changes. This is great for development, but it’s not a sustainable solution for a team or for deployment.

Part 2: The Monorepo Magic

Having to manually build sub-folders is cumbersome. The answer is to treat your entire Strapi project as a monorepo. We can do this easily with npm’s built-in workspaces feature.

Define your workspaces. In your main project’s package.json, tell npm where to find your sub-packages.
package.json
```
1
// ...existing code...
2
"workspaces": [
3
    "packages/*"
4
],
5
// ...existing code...
```
Now, when you run npm install from the root, npm will also install dependencies for your local plugin. You can test this by deleting all node_modules folders and running npm install from your project’s root directory.
Isolate your TypeScript configs. You don’t want the main Strapi TypeScript compiler to process your plugin’s source code; the plugin has its own build process. Add an exclude rule to your root tsconfig.json.
tsconfig.json
```
1
// ...existing code...
2
"exclude": [
3
    // ...existing code...
4
    "packages/**",
5
]
```
Unify the build process. This is the key step. Instead of building each piece separately, you can run a single command from the root folder to build all workspaces. The --workspaces flag tells npm to run the build script in every package defined in your workspaces array.
Terminal window
```
npm run build --workspaces
```
This command will call the build script in packages/my-local-plugin, creating its dist folder.

Streamline with npm scripts. To make the process even smoother, let’s add some helper scripts to the root package.json. This combines building the plugins and the main Strapi app into a single command.

1
// ...existing code...
2
"scripts": {
3
    // ...existing code...
4
    "build:plugins": "npm run build --workspaces",
5
    "build:strapi": "strapi build",
6
    "build": "npm run build:plugins && npm run build:strapi",
7
    "dev": "strapi develop",
8
    "start": "strapi start",
9
    // ...existing code...
10
},
11
// ...existing code...

Build and run. Now, you have a simple, unified workflow.

For development, run Strapi as usual, but remember to build the plugin first:
Terminal window
```
npm run build:plugins
npm run dev
```
For production, the process is just as clean:
Terminal window
```
npm run build
npm run start
```

That’s it! With this setup, anyone can clone your project and get it running with a familiar npm install and npm run build. No more cd-ing into sub-folders or manual build steps. Just a simple, clean, and efficient workflow.