Plugin development repo (monorepo) organization

[late ingot]

What is the best way for open-source plugin development repo organization? For example, when I develop a plugin, it requires a Medusa instances for testing and debugging. How should I organize my repositories to quickstart development environment and showcases?

I see 2 options:

1. With two repos

# 1st - plugin repo
/                                 # your published medusa-plugin
└─ package.json

# 2nd - examples repo
/
├─ medusa-store/                  # Medusa Admin
├─ medusa-store-storefront/       # Medusa storefront
└─ medusa-plugin/                 # git submodule reference

The 1st repo - for the medusa-plugin itself, and the 2nd (monorepo) - for medusa-store, medusa-store-storefront, and medusa-plugin (as a git submodule referencing the 1st repo, for local development with yalc)

2. With only one repo (monorepo)
In that case, the folders structure could look like the 2nd repo of the first approach, but with some tooling applied for managing monorepos (eg. lerna or similar) and publishing the plugin package to NPM.

What are your thoughts?

[late ingot]

Here is an answer from ChatGPT o4-mini-high - https://chatgpt.com/share/680ce547-d4e8-8007-a8f4-eb50474900ba

It suggests similar to my 2nd proposed option but in a structure like this:

/
├─ packages/                      # “real” workspaces
│   └─ medusa-plugin/             # your published medusa-plugin
│       └─ package.json
│
└─ examples/                      # playgrounds for local dev & demos
    ├─ medusa-store/              # a Medusa server that depends on ../packages/medusa-plugin
    └─ medusa-store-storefront/   # storefront pointing at the demo store

I would reduce 1 level (for development of one isolated plugin) to smth like this:

/
├─ medusa-plugin/                 # your published medusa-plugin
│   └─ package.json               
│
└─ examples/                      # playgrounds for local dev & demos
    ├─ medusa-store/              # a Medusa server that depends on ../medusa-plugin
    └─ medusa-store-storefront/   # storefront pointing at the demo store

[rapid kindle]

Hi @late ingot
As mentioned in the https://discord.com/channels/876835651130097704/1331569598893527071, please do not ping core team members

[minor rapids]

@late ingot have you figured out best approach that works for you?

[late ingot]

Hi, yes. I think the best is these ones depending on your needs:

For 1 plugin and 1 example:

/
- packages/
  - my-plugin/
- examples/
  - medusa-store/
  - medusa-storefront/

For 1 plugin and multiple examples:

/
- packages/
  - my-plugin/
- examples/
  - my-example-1/
    - medusa-store/
    - medusa-storefront/
  - my-example-2/
    - medusa-store/
    - medusa-storefront/

For multiple plugins and multiple examples:

/
- packages/
  - my-plugin-1/
  - my-plugin-2/
- examples/
  - my-example-1/
    - medusa-store/
    - medusa-storefront/
  - my-example-2/
    - medusa-store/
    - medusa-storefront/

This approach offers continuity for multiple plugins and similar ci-cd setup for different repos.
Also it is align with node repos best practices

[topaz orbit]

@late ingot Have u a problem to import the plugin in this way?
I had the problem with resolve.

[late ingot]

@topaz orbit I had some issues, but I resolved them. If you provide some more context about your issues, I could prb help

[topaz orbit]

Well, I'm looking a good way to build a private plugin (and public also).

Case:

1. Would be the best to use .yalc to development
2. Would to have a code in the repo

I tryied to have a "package" in the same repository where is the back-end (even the same directory, but this don't work).
When I imported the plugin for example "plugins/[plugin]" then I had the error that it can't resolve.

[late ingot]

@topaz orbit here is complete manual instructions for the structure like that:

- packages/
  - my-medusa-plugin/
- examples/
  - medusa/
  - medusa-storefront/
  - docker-compose.yml

uploaded in the file

and docker-compose.yml:

services:
  db:
    image: postgres
    restart: always
    ports:
      - 5432:5432
    volumes:
     - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: supersecret
      POSTGRES_USER: medusa
      POSTGRES_DB: my-medusa
  adminer:
    image: adminer
    restart: always
    depends_on: 
      - db
    ports:
      - 8080:8080

volumes:
  pgdata:

[late ingot]

@topaz orbit @minor rapids

Hi all!

I've just published the CLI tool create-medusa-plugin to bootstrap the plugin monorepo structure like this:

/
└── my-plugin-monorepo/
    ├── examples/
    │   └── my-plugin-example/
    │      ├── medusa/
    │      └── medusa-storefront/
    ├── packages/
    │   └── my-plugin/
    ├── package.json
    └── README.md

It uses the official create-medusa-app under the hood to scaffold Medusa projects—including the plugin, backend and storefront folders. This ensures your setup follows best practices and remains fully compatible with the Medusa ecosystem by leveraging the official Medusa app generator.

NPM: https://www.npmjs.com/package/create-medusa-plugin
GitHub: https://github.com/sergkoudi/create-medusa-plugin

Try using it with just a simple command:

npx create-medusa-plugin

UPD

I renamed this CLI to create-medusa-plugin

[topaz orbit]

Nice! I will check.
Thanks for your help :_)