Deploy preview: https://deploy-preview-19014--material-ui-x.netlify.app/

Bundle size report

Details of bundle changes

Generated by 🚫 dangerJS against c1d8bbd

You can do:

❯ pnpm start --port 3002

> @8.9.2 start /Users/belchior/Documents/mui/mui-x
> pnpm i && pnpm docs:dev --port 3002

Scope: all 27 workspace projects
Lockfile is up to date, resolution step is skipped
Already up to date

╭ Warning ───────────────────────────────────────────────────────────────────────────────────╮
│                                                                                            │
│   Ignored build scripts: core-js.                                                          │
│   Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.   │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

Done in 1.1s using pnpm v10.13.1

> @8.9.2 docs:dev /Users/belchior/Documents/mui/mui-x
> pnpm --filter docs dev --port 3002


> docs@ dev /Users/belchior/Documents/mui/mui-x/docs
> next dev --port 3001 --port 3002

   ▲ Next.js 15.4.4
   - Local:        http://localhost:3002
   - Network:      http://192.168.2.92:3002
   - Experiments (use with caution):
     · esmExternals
     ✓ scrollRestoration

 ✓ Starting...
   Using tsconfig file: ../tsconfig.dev.json
   Disabled SWC as replacement for Babel because of custom Babel configuration "babel.config.js" https://nextjs.org/docs/messages/swc-disabled
   `compiler` options in `next.config.js` will be ignored while using Babel https://nextjs.org/docs/messages/ignored-compiler-options
Considering various locales for SSR
 ✓ Ready in 1845ms

You can do:

❯ pnpm start --port 3002

I'm aware I can, but using PORT I can have a export PORT=3002 in an ignored file and load it automatically in my terminal env for each different copy of the repo I have. Then I can do pnpm docs:env without caring about which folder I'm in.

I'm aware I can, but using PORT I can have a export PORT=3002 in an ignored file and load it automatically in my terminal env for each different copy of the repo I have. Then I can do pnpm docs:env without caring about which folder I'm in.

If there will be a file per repo anyway, instead of export PORT=3002, would it make sense to have the file run pnpm start --port 3002?

I don't have a big issue with using cross-env-shell here, it's just that this change is workflow dependent, and we won't be able to fulfill everyone's use cases. It also might introduce issues for Windows users, in case something doesn't work well.

If you feel like running ./start-dev.sh that contains pnpm start --port 3002 isn't great, then I suppose the code change in this PR is acceptable.

it's just that this change is workflow dependent, and we won't be able to fulfill everyone's use cases

Well put, this resonates with me. But we need to unlock this use-case. In your workflow, instead of overriding the environment, would it be possible to override the command? pnpm docs:dev --port <my other port> should just work, you can define this arg multiple times.

it's just that this change is workflow dependent, and we won't be able to fulfill everyone's use cases.

I would argue that the original code is MORE workflow dependent than the change itself. It is correcting for the possibility that we have material/docs running at the same time.

It also might introduce issues for Windows users, in case something doesn't work well.

It doesn't, we already use cross-env, so using cross-env-shell should work for everything.

I fail to see what concrete issue you are worried about here, since my change only allows for more possibilities, rather than limiting anything.

Ideally we wouldn't use the --port if nextjs was able to support PORT=..., but it doesn't, so this is the next best approach to simplify running multiple docs without having to type out the port often.

Ideally we wouldn't use the --port if nextjs was able to support PORT=...

FWIW, PORT=3002 next dev does work. I checked it in the latest version though.

Ideally we wouldn't use the --port if nextjs was able to support PORT=...

FWIW, PORT=3002 next dev does work. I checked it in the latest version though.

Sorry I got confused. It doesn't support PORT in the next.config.local.js env declaration.

Still, for PORT=3002 to work with pnpm docs:dev we would have to remove the force --port 3001, which I don't think is wise at this point 🫠

I would argue that the original code is MORE workflow dependent than the change itself. It is correcting for the possibility that we have material/docs running at the same time.

Yeah, that's true. I wonder if that assumption is still useful.

next dev will automatically choose the next port if one is full.

> next dev

 ⚠ Port 3000 is in use by process 51198, using available port 3001 instead.
   ▲ Next.js 15.4.5
   - Local:        http://localhost:3001
   - Network:      http://192.168.2.92:3001
   - Experiments (use with caution):
     · esmExternals
     ✓ scrollRestoration

So we could consider removing the port override.

It doesn't, we already use cross-env, so using cross-env-shell should work for everything.

Great 👍

I fail to see what concrete issue you are worried about here, since my change only allows for more possibilities, rather than limiting anything.

My point isn't in this change per se. It's mostly that if we're catering to one workflow, then when someone else has another workflow that clashes with this one, we'll need to handle both workflows. It's just a preventive measure.

Ideally we wouldn't use the --port if nextjs was able to support PORT=..., but it doesn't, so this is the next best approach to simplify running multiple docs without having to type out the port often.

Sure, makes sense.

Also, regarding this question, wouldn't it work for your workflow?

If there will be a file per repo anyway, instead of export PORT=3002, would it make sense to have the file run pnpm start --port 3002?

If not, I think we can merge this and reassess the default port of 3001 if more changes are required.

My point isn't in this change per se. It's mostly that if we're catering to one workflow, then when someone else has another workflow that clashes with this one, we'll need to handle both workflows. It's just a preventive measure.

How so? If our initial state makes it work only in a specific workflow? This change only makes the project more configurable.

My entire point is that the current workflow is flawed. I'm keeping the current behaviour and making it support the common behaviour of accepting PORT= that pretty much every server application supports, all this without removing the current implementation to not create issues.

I can't see any way this will clash with any workflow whatsoever since every part of this is overridable. 🤔

Also, regarding this question, wouldn't it work for your workflow?

I can manually force the port, my point is that it is tiring. I have 3 different versions of the same repo. I have to check which one I'm in, then select the port I want to use.

My local config doesn't run anything per-se. It only loads a .env.local config file and provide it to the server.

My goal is to simply run whatever scripts I want with the configuration I provide.

I'm just asking for ppl to review this at face value.

• It is a one-line change.
• It doesn't change any of the current behaviour.
• I can't think of no other way to allow configuring through env variables while still accepting the current default port.
• Accepting PORT is the common behaviour of pretty much every server application
• This implementation works in linux, windows and macos.

I fail to see what all the fuss is about, and if we want to discuss about removing the default port I would move it to a different PR, as that is not the goal here, but I also find that discussion has no value in itself, since everything works.

Another option is to run your dev command like pnpm -F docs exec next dev

Then you can specify whatever PORT variable you want. e.g.

PORT=3009 pnpm -F docs exec next dev

I'm just asking for ppl to review this at face value.

I think the problem with this PR is that it's adding yet another layer of config overrides. We now have

• config set in docs infra
• config set by environment variables in docs infra (e.g. netlify)
• config set by the X next.config.js
• config set by the local next.js override
• config set by the next.js start command
• and now config set by the env vars in the next.js start command

I agree that it's "It is a one-line change" and from the perspective of an X maintainer a not so significant one. But from the code-infra perspective it's yet another layer of complexity to manage and another local breaking point to account for. From code infra perspective, the complexity compounds as each project starts adding their own overrides system. Managing complexity here means aiming at taking override layers away, and that's why I think this implementation intuitively rubs against the grain of the participants in this thread.