Improve general contribution guidelines

[NicolasGorga]

Package.json file

...

Node.js version

...

Database and its version

...

Operating system name and version

...

Browser name

No response

What happended?

The general contribution guidelines mainly focuses on explaining how actions around Git should be executed (branch names, PR descriptions, etc), but doesn't mention anything around setting the local environment.

I personally have been using https://www.npmjs.com/package/medusa-dev-cli which is never mentioned, but recently started having problems where it wasn't copying my modifications in a reliable manner to my test project, which made me lose a lot of time when contributing for things i would otherwise have done in a manner of minutes.

Expected behavior

The general contribution guidelines has a dedicated section for "Local Development" including detailed step by step instructions indicating how to setup the local environment for a smooth experience while working on contributions.

Also mentions common troubleshooting and any relevant tools to be used while developing.

Actual behavior

There are no indications as to how to setup the local environment.

Link to reproduction repo

...

[NicolasGorga]

Hey @shahednasser could i bother you to give me the instructions i should follow? Maybe i am doing things differently than before (where i didn't have the problems i am having with local Medusa development), but i see that using medusa-dev-cli is copying things to my test project /node_modules/packages, instead of the specific package inside /node_modules/@medusajs/*

It is making things hard for me to contribute. The latest, trying to make a contribution to /dashboard UI project, and i see it is copied to /node_modules/packages/admin/dashboard

[shahednasser]

@willbouch can you help out here?

[willbouch]

Personally, what I do is that I have the medusa repo cloned and a test-project created. I make modifications in the medusa core repo, build and then test on my test-project by pointing the dependencies to my local core repo. The package.json looks like this:

{
  "name": "test",
  "version": "0.0.1",
  "description": "A starter for Medusa projects.",
  "author": "Medusa (https://medusajs.com)",
  "license": "MIT",
  "keywords": [
    "sqlite",
    "postgres",
    "typescript",
    "ecommerce",
    "headless",
    "medusa"
  ],
  "scripts": {
    "build": "medusa build",
    "seed": "medusa exec ./src/scripts/seed.ts",
    "start": "medusa start",
    "dev": "medusa develop",
    "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPT1IONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
    "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"
  },
  "resolutions": {
    "@medusajs/test-utils": "file:../medusa/packages/medusa-test-utils",
    "@medusajs/api-key": "file:../medusa/packages/modules/api-key",
    "@medusajs/auth": "file:../medusa/packages/modules/auth",
    "@medusajs/cache-inmemory": "file:../medusa/packages/modules/cache-inmemory",
    "@medusajs/cache-redis": "file:../medusa/packages/modules/cache-redis",
    "@medusajs/cart": "file:../medusa/packages/modules/cart",
    "@medusajs/locking": "file:../medusa/packages/modules/locking",
    "@medusajs/currency": "file:../medusa/packages/modules/currency",
    "@medusajs/customer": "file:../medusa/packages/modules/customer",
    "@medusajs/event-bus-local": "file:../medusa/packages/modules/event-bus-local",
    "@medusajs/file": "file:../medusa/packages/modules/file",
    "@medusajs/file-local": "file:../medusa/packages/modules/providers/file-local",
    "@medusajs/fulfillment": "file:../medusa/packages/modules/fulfillment",
    "@medusajs/fulfillment-manual": "file:../medusa/packages/modules/providers/fulfillment-manual",
    "@medusajs/index": "file:../medusa/packages/modules/index",
    "@medusajs/inventory": "file:../medusa/packages/modules/inventory",
    "@medusajs/medusa": "file:../medusa/packages/medusa",
    "@medusajs/notification": "file:../medusa/packages/modules/notification",
    "@medusajs/notification-local": "file:../medusa/packages/modules/providers/notification-local",
    "@medusajs/order": "file:../medusa/packages/modules/order",
    "@medusajs/payment": "file:../medusa/packages/modules/payment",
    "@medusajs/pricing": "file:../medusa/packages/modules/pricing",
    "@medusajs/product": "file:../medusa/packages/modules/product",
    "@medusajs/promotion": "file:../medusa/packages/modules/promotion",
    "@medusajs/region": "file:../medusa/packages/modules/region",
    "@medusajs/sales-channel": "file:../medusa/packages/modules/sales-channel",
    "@medusajs/stock-location": "file:../medusa/packages/modules/stock-location",
    "@medusajs/store": "file:../medusa/packages/modules/store",
    "@medusajs/tax": "file:../medusa/packages/modules/tax",
    "@medusajs/user": "file:../medusa/packages/modules/user",
    "@medusajs/workflow-engine-inmemory": "file:../medusa/packages/modules/workflow-engine-inmemory",
    "@medusajs/link-modules": "file:../medusa/packages/modules/link-modules",
    "@medusajs/admin-bundler": "file:../medusa/packages/admin/admin-bundler",
    "@medusajs/admin-sdk": "file:../medusa/packages/admin/admin-sdk",
    "@medusajs/admin-shared": "file:../medusa/packages/admin/admin-shared",
    "@medusajs/dashboard": "file:../medusa/packages/admin/dashboard",
    "@medusajs/admin-vite-plugin": "file:../medusa/packages/admin/admin-vite-plugin",
    "@medusajs/ui": "file:../medusa/packages/design-system/ui",
    "@medusajs/icons": "file:../medusa/packages/design-system/icons",
    "@medusajs/toolbox": "file:../medusa/packages/design-system/toolbox",
    "@medusajs/ui-preset": "file:../medusa/packages/design-system/ui-preset",
    "@medusajs/utils": "file:../medusa/packages/core/utils",
    "@medusajs/types": "file:../medusa/packages/core/types",
    "@medusajs/core-flows": "file:../medusa/packages/core/core-flows",
    "@medusajs/orchestration": "file:../medusa/packages/core/orchestration",
    "@medusajs/cli": "file:../medusa/packages/cli/medusa-cli",
    "@medusajs/modules-sdk": "file:../medusa/packages/core/modules-sdk",
    "@medusajs/workflows-sdk": "file:../medusa/packages/core/workflows-sdk",
    "@medusajs/framework": "file:../medusa/packages/core/framework",
    "@medusajs/auth-emailpass": "file:../medusa/packages/modules/providers/auth-emailpass",
    "@medusajs/locking-redis": "file:../medusa/packages/modules/providers/locking-redis",
    "@medusajs/locking-postgres": "file:../medusa/packages/modules/providers/locking-postgres",
    "@medusajs/telemetry": "file:../medusa/packages/medusa-telemetry",
    "@medusajs/settings": "file:../medusa/packages/modules/settings",
    "@medusajs/draft-order": "file:../medusa/packages/plugins/draft-order",
    "@medusajs/deps": "file:../medusa/packages/deps",
    "@medusajs/caching-redis": "file:../medusa/packages/modules/providers/caching-redis",
    "@medusajs/caching": "file:../medusa/packages/modules/caching"
  },
  "dependencies": {
    "@medusajs/admin-sdk": "file:../medusa/packages/admin/admin-sdk",
    "@medusajs/cli": "file:../medusa/packages/cli/medusa-cli",
    "@medusajs/framework": "file:../medusa/packages/core/framework",
    "@medusajs/medusa": "file:../medusa/packages/medusa",
    "@mikro-orm/core": "6.5.5",
    "@mikro-orm/knex": "6.5.5",
    "@mikro-orm/migrations": "6.5.5",
    "@mikro-orm/postgresql": "6.5.5",
    "awilix": "^8.0.1",
    "pg": "^8.13.0"
  },
  "devDependencies": {
    "@medusajs/test-utils": "file:../medusa/packages/medusa-test-utils",
    "@mikro-orm/cli": "6.5.5",
    "@swc/core": "1.5.7",
    "@swc/jest": "^0.2.36",
    "@types/jest": "^29.5.13",
    "@types/node": "^20.0.0",
    "@types/react": "^18.3.2",
    "@types/react-dom": "^18.2.25",
    "jest": "^29.7.0",
    "prop-types": "^15.8.1",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "ts-node": "^10.9.2",
    "typescript": "^5.6.2",
    "vite": "^5.2.11",
    "yalc": "^1.0.0-pre.53"
  },
  "engines": {
    "node": ">=20"
  }
}

What do you think? This has proven to be the fastest way for me and I know other developers in the team do it like this too. Lmk what you think @NicolasGorga

[NicolasGorga]

@willbouch Hey, oh I see, so you don't use https://www.npmjs.com/package/medusa-dev-cli

Is there any command you executed to get the initial dependencies pointing to your local Medusa core repo? @shahednasser If this is the recommended approach, i can create a pull request to update CONTRIBUTING.md if that is okay with you?

[willbouch]

IS this the "recommended approach" it is a good question. I was told to do that when I joined Medusa about 2 months ago haha. I did not even know about the dev-cli. Let me get the team's opinion

[NicolasGorga]

Haha fair enough. Awesome, i'll wait for you then before creating a PR for the Contribuiting.md and when i get some time from work will try your approach

[willbouch]

Yep, 2 confirmed that this is what they do as well

[shahednasser]

@NicolasGorga feel free to open a PR 🙏

[NicolasGorga]

Awesome will do after a meeting i have now :) Many thanks to both of you

[NicolasGorga]

Was testing this approach now and i see the following:

• Making changes in forked core and testing them in test project is time consuming:
  • yarn build core (or watch provided package has it, which is better)
  • Here the friction: Go to test project, remove node_modules and run yarn install.

I tried running yarn install --check-files and yarn cache clean && yarn install but my node_modules still showed the contents previous to me changing the core project. Only removing node_modules and reinstalling do i see the changes. @willbouch do you do this or am i missing something?

[willbouch]

Was testing this approach now and i see the following:

• Making changes in forked core and testing them in test project is time consuming:

  • yarn build core (or watch provided package has it, which is better)
  • Here the friction: Go to test project, remove node_modules and run yarn install.

I tried running yarn install --check-files and yarn cache clean && yarn install but my node_modules still showed the contents previous to me changing the core project. Only removing node_modules and reinstalling do i see the changes. @willbouch do you do this or am i missing something?

I actually do the same thing. I'll check with the others if they found a way around that. I always have this rm -R node_modules && yarn && yarn dev ready