A TanStack Start app runs on port 3000 while you work on it. If another app already uses that port, or you want two apps side by side, you can move it to another port with one change in package.json, or for a single run with one command.
Syntax
The dev script starts Vite’s dev server. Its port comes from this option:
vite dev --port <port>
vite devstarts the dev server.--portsets the port it listens on.<port>is the port number, such as3001.
The Vite CLI reference lists this option.
Prerequisites
- A TanStack Start app created with the TanStack CLI, as in Part 2.
- A terminal open in the app’s folder.
Step 1: Change the Port in package.json
Open package.json. The CLI writes the port into the dev script. Change 3000 to the port you want, for example 3001:
package.json (excerpt)
"dev": "vite dev --port 3001",
Step 2: Start the Dev Server
npm run dev
npm notice run dev
npm notice run vite dev --port 3001
11:16:59 AM [vite] ⬥ Netlify Environment loaded
11:16:59 AM [vite] ⬥ Netlify Middleware loaded. Emulating features: aiGateway, blobs, database, environmentVariables, functions, geolocation, headers, images, redirects, server, static.
11:16:59 AM [vite] ⬥ Netlify 💭 Linking this project to a Netlify site lets you deploy your site, use any environment variables defined on your team and site and much more. Run npx netlify init to get started.
VITE v8.3.8 ready in 1932 ms
➜ Local: http://localhost:3001/
➜ Network: use --host to expose
➜ press h + enter to show help
11:17:00 AM [vite] (ssr) connected.
Open http://localhost:3001 in your browser to see the app.
Change the Port for One Run Only
To use another port once, without editing package.json, add -- and the option to the command. npm passes everything after -- on to the script (npm docs):
npm run dev -- --port 3002
npm notice run dev
npm notice run vite dev --port 3000 --port 3002
11:17:19 AM [vite] ⬥ Netlify Environment loaded
11:17:19 AM [vite] ⬥ Netlify Middleware loaded. Emulating features: aiGateway, blobs, database, environmentVariables, functions, geolocation, headers, images, redirects, server, static.
11:17:19 AM [vite] ⬥ Netlify 💭 Linking this project to a Netlify site lets you deploy your site, use any environment variables defined on your team and site and much more. Run npx netlify init to get started.
VITE v8.3.8 ready in 1945 ms
➜ Local: http://localhost:3002/
➜ Network: use --host to expose
➜ press h + enter to show help
11:17:22 AM [vite] (ssr) connected.
The script now reads vite dev --port 3000 --port 3002, and Vite uses the last port given: 3002.
If You Use Netlify Dev
The [dev] section of netlify.toml has targetPort = 3000. Netlify Dev, the Netlify CLI’s local server, uses it to find your app. If you run the app through Netlify Dev, change targetPort to the same port (Netlify docs).
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Leaving out -- in npm run dev -- --port 3002 | npm reads the option itself, so Vite never gets it | Put -- before the option |
Changing only netlify.toml | The dev server still uses the port in package.json | Change the dev script first |
Troubleshooting
| Problem | Fix |
|---|---|
The terminal says Port 3001 is in use, trying another one... | Another app has that port. Vite uses the next free one, so open the address it prints after Local:. |
FAQ
Can I make Vite stop instead of picking another port? Yes. Vite’s server.strictPort setting makes it exit when the port is in use.
Conclusion
The port lives in the dev script in package.json. Change it there to move the app for good, or add -- --port to npm run dev for a single run.
Additional Resources
Related
- TanStack Start Tutorial — Part 2: Create Your First TanStack Start App
- TanStack Start Tutorial for Beginners, every part of the series
TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.