Deploy a React and Vite site to production

Choose the right deployment path before building

This walkthrough uses a static upload. The browser receives HTML, CSS and JavaScript; it does not start your development server. You can use your own app or the small downloadable example below. First check whether the app needs a server process as well as a frontend.

Prepare the project, runtime and destination

• Use Node.js 22.12+ on a supported release line and npm. CLI 0.3.0 requires Node 22+; this example was compiled with Node 22.20.0, Vite 8.3.1 and React/React DOM 19.3.0. Check your own app’s engine requirements before switching runtimes.
• Have a Shipvela account and install its CLI from the versioned setup instructions. Do not substitute an unverified npm package with a similar name.
• Identify the app’s build script and output directory. Review any existing shipvela.json: it determines which project a subsequent publish updates.
• Configure only public frontend values before building. A private API key must not be placed in a VITE_ value. Read the environment variable guide if the app needs configuration.

node --version
npm --version
shipvela --version

The first two commands report installed runtime versions; the copied CLI checked for this guide reports 0.3.0. A successful version check does not log you in or prove that hosting is configured. Current Vite requirements are documented in Vite’s getting-started guide.

Start with a reproducible example or your existing app

Download the React/Vite example, extract it and open shipvela-react-vite-fixture in your terminal. It includes source, a lockfile, a README and a build inspector. It contains no credentials, remote API calls or automatic deployment script. The example displays the current path; it is a small routing check, not a full router library.

cd shipvela-react-vite-fixture
npm ci --ignore-scripts

For an existing app, work in its root instead. Use its documented installation process and a committed npm lockfile. The example deliberately needs no install lifecycle scripts; do not blindly add --ignore-scripts to an app whose native dependencies require them. If package.json and its lockfile disagree, fix that mismatch locally instead of deploying a different dependency tree. See npm ci.

For the example, create .env.production.local with these harmless demonstration values. Its .gitignore excludes local env files. These values are not private credentials.

VITE_SITE_LABEL=Shipvela production fixture
VITE_SHOW_BANNER=false
PRIVATE_SENTINEL=PRIVATE_SENTINEL_MUST_NOT_BE_BUNDLED_72

The label intentionally appears in the public bundle. The unprefixed sentinel tests the default Vite exposure rule; it is not a substitute for reviewing all generated assets for sensitive content.

Build and inspect the production files

npm run build
node scripts/inspect-build.mjs

The local build completed and generated dist/index.html plus a hashed JavaScript asset. The example’s inspector returned the following values. Hashed filenames and timings can change; this check is about the artifact and its contents.

{
  "indexHtml": true,
  "javascriptFiles": 1,
  "publicLabelPresent": true,
  "unprefixedSentinelPresent": false,
  "falseFlagEnablesBanner": false,
  "productionModePresent": true
}

The inspector belongs to the downloadable example, not the Shipvela CLI. For your own app, inspect its output or adapt the script. Every browser-delivered file should be treated as public, even if the originating environment variable was hidden in a dashboard.

The upload limit is 50 MB and 5,000 files. Large media may need an appropriate separately managed asset service or a deliberate reduction in output; do not upload the source tree to get around an output problem.

Check a local production preview

npm run preview -- --host 127.0.0.1

Open the URL printed by Vite, then visit /guide/deep-link directly. In the example the heading should show the configured label and the path line should reflect that URL. This browser inspection is a step for you to perform; the recorded fixture evidence covers local compilation and HTTP responses, not a live hosted browser session.

Check the Network panel for failed JavaScript, CSS and image requests. A page that works under npm run dev can still fail when its production asset URLs or configuration differ. Stop preview with Ctrl+C after inspection. Vite preview is a local inspection tool, not the server you keep running in production.

Publish the reviewed output with the existing CLI

shipvela login
shipvela publish dist --name my-react-site --spa --json

Login opens Shipvela’s approval page. Compare the terminal code and approve only the request you initiated. The first publish creates an upload project and writes shipvela.json; the CLI sends the archive to Shipvela’s authenticated validation endpoint and waits for the particular hosting job it starts.

If a project link already exists, the publish updates that project. --name and --spa are creation choices; adding them to a later publish does not create a separate site or repair an existing routing configuration. Check the linked project’s build settings if it was created with the wrong routing mode.

With --json, progress is on stderr and the final result or error object is on stdout. A successful result contains projectId, job and url; verify that the job status is SUCCEED. A login response, packaging message or upload acknowledgement is not the final deployment receipt. No hosted receipt is fabricated in this article.

shipvela status --json
shipvela logs --job JOB_ID --json

The CLI waits by default for publish. If it times out, the job may still be running. Inspect status before repeating the mutation. The CLI does not automatically retry a publish mutation merely because a response was lost.

Verify the hosted page, assets and direct routes

• Open the actual returned HTTPS URL and confirm a visible detail from the intended build. Do not copy a URL from an earlier unrelated project.
• Load a direct client route in a new tab and refresh it. This checks the hosting fallback as well as the app’s route handling.
• Inspect the JavaScript/CSS requests that the HTML references. They should load with the expected content, not a 404 page or HTML fallback disguised as a script.
• Exercise a meaningful interaction. If the app calls an external API, check its production URL, authorization and CORS behavior separately; successful hosting does not configure that API.
• Retain the job ID and build version in your release notes. Add a custom domain only after the default hosted URL works.

For an update, make the intended source change, run the build again, inspect the output, then run shipvela publish dist --json from the same linked project root. An old dist folder republishes old code even when your source files changed.

Diagnose the failing layer before publishing again

For base-path and stale-chunk behavior, consult Vite’s production build guide. For imported versus public assets, use Vite’s asset guide. Avoid repeatedly reloading on every error: a broken path will remain broken and a reload can discard unsaved user input.

What was checked, and what still needs your acceptance test

The downloadable example was compiled locally with the versions listed above. Its generated bundle passed the shown inspection. Separate isolated tests exercised the real CLI archive packager, exclusion and rejection rules, and CLI control flow against clearly synthetic responses. These checks do not certify your app or prove that a production deployment, custom domain, OAuth flow or Claude Code session succeeded.

This workflow serves a static frontend. It does not provision databases, run arbitrary backend processes, or guarantee compatibility with every AI-generated project. When your own successful job, HTTPS URL, direct routes and key interaction pass, you have completed the deployment acceptance check for that build.