Com publicar React amb Vite i evitar el 404 en recarregar

Una web React que veus a localhost encara depèn del teu ordinador. Si Vite genera fitxers estàtics i l’aplicació no necessita un servidor propi, pots construir aquests fitxers i publicar-los des de Git. Després pots apagar el servidor de desenvolupament.

Aquest recorregut utilitza un exemple original React i Vite amb llicència MIT. La demo publicada té dues rutes: la portada i /about. Inclou una imatge pròpia, CSS i una variable pública de construcció. No implementa inici de sessió, pagaments, API ni base de dades.

Si el projecte utilitza Astro i Markdown, consulta la guia de publicació estàtica des de Git, amb rutes i URL canonical comprovades en una demo publicada.

Si la interfície React es carrega però les peticions a l’API fallen després de publicar-la, segueix el diagnòstic de frontend i API en producció.

Comprova què ha generat l’eina d’IA

Busca package.json i revisa’n els scripts. En aquest exemple, build executa Vite i genera dist. React no determina tot sol el tipus d’allotjament: una interfície que crida Supabase, una API o un servidor també necessita aquests serveis i les credencials ben configurades.

No eliminis les dependències de backend per fer passar una aplicació per estàtica. Consulta quin allotjament necessita una web creada amb IA si no saps quina part executa el navegador i quina necessita servidor. Aquesta recepta tampoc no demostra suport del renderitzat al servidor de Next.js.

Prepara un repositori reproduïble

Fes un fork o copia l’exemple al teu compte de GitHub, mantenint la llicència. Inclou package.json, package-lock.json, index.html, src, public i la configuració de Vite. El fitxer de bloqueig permet que npm ci instal·li les versions registrades; no actualitza les dependències automàticament.

L’exemple necessita Node 22.19.0 o posterior. Construeix-lo primer al teu equip:

npm ci
npm run build

Comprova que existeix dist/index.html i que els fitxers de CSS i JavaScript són a dist/assets. npm run dev i npm run preview serveixen per desenvolupar i comprovar localment; no són el procés de producció d’aquesta publicació estàtica.

Configura Projects per a aquest exemple

Connecta el proveïdor Git i selecciona el repositori seguint la documentació de Projects. Revisa els permisos abans d’autoritzar-los. Aquests són els ajustos provats:

Aquests valors corresponen a aquest repositori. Un monorepo, un altre script o una sortida personalitzada necessita la seva configuració. No publiquis node_modules ni la teva carpeta personal.

Evita el 404 en obrir una ruta directament

Quan navegues des de la portada, React pot canviar l’URL a /about sense demanar un altre HTML. En recarregar, el navegador demana /about a l’allotjament. Si aquest fitxer no existeix i no hi ha fallback, obtindràs 404 encara que l’enllaç funcionés abans.

A Hostbrid, aquest exemple activa el fallback amb el fitxer public/.hostbrid-spa. Vite el copia a l’arrel de dist. L’allotjament serveix index.html per a les rutes de navegador del lloc que inclou aquest marcador i té un índex. Els llocs sense marcador mantenen el seu comportament habitual. El marcador no es lliura per HTTP i els fitxers de recursos absents continuen retornant 404.

Comprova que l’exportació conserva els fitxers que comencen per punt. No n’hi ha prou de crear el marcador en una carpeta que el build no copia. Una ruta desconeguda pot retornar l’HTML amb estat 200 i mostrar «Pàgina no trobada» a React: això no la converteix en una pàgina vàlida per al SEO. Defineix les rutes reals i revisa el renderitzat i la indexació abans de publicar moltes URL.

Pantalla en blanc: identifica la petició que falla

Obre les eines del navegador, selecciona Network, recarrega i examina la petició que falla. Comprova l’URL, l’estat, el tipus de contingut i la resposta. Una portada que retorna 200 no demostra que s’hagi carregat el JavaScript.

• El document /about retorna 404: revisa el marcador i el fallback descrits més amunt.
• El JavaScript o el CSS retorna 404: compara l’URL demanada amb els fitxers construïts. Publica tota la carpeta dist i comprova que l’HTML i els recursos pertanyen a la mateixa construcció.
• El JavaScript retorna 200 amb HTML: el servidor està retornant una pàgina, potser l’índex o un error, on el navegador espera codi. Enviar totes les peticions a index.html no ho resol; els recursos absents han de continuar retornant 404.
• Els fitxers es carreguen, però la pantalla continua en blanc: revisa la consola. Un error de l’aplicació, una API externa o una variable absent necessita un diagnòstic diferent del fallback.

El nostre exemple es publica a l’arrel del seu subdomini. Si prepares una instal·lació sota /demo/ en un altre servidor, l’opció base de Vite ajusta els camins dels recursos durant la construcció; configura el prefix del router per separat. base: './' no resol qualsevol error de recàrrega en rutes profundes. Aquesta guia no demostra que Projects admeti publicacions sota qualsevol prefix.

També pots utilitzar el nostre diagnòstic estàtic original amb llicència MIT. Amb Node 22.23.3, descarrega la versió provada i executa:

git clone https://github.com/ocentelles/hostbrid-static-diagnostics.git
cd hostbrid-static-diagnostics
git checkout 203e71e33e9864f8048dccee3d886fa3c87dcb1c
node --version
node diagnose.mjs https://hostbrid-react-demo.hostbrid.dev/

Substitueix l’URL de la demo per la de la teva web pública. No cal instal·lar dependències. Comprova l’HTML i les referències directes a JavaScript i CSS del mateix origen; no executa React ni verifica imatges, API o rutes internes. Retorna JSON i un codi de sortida diferent de zero si detecta errors o no pot completar una comprovació. La demo de l’ordre va passar tres peticions GET; l’eina té 28 proves HTTP locals. Un resultat correcte no substitueix les proves al navegador.

També hem publicat l’exemple original de rutes i recursos: sis casos locals amb bases incorrectes, el prefix del router i HTML servit com a JavaScript. El README explica com reproduir-los amb Node i Chrome; aquest assaig no afegeix capacitats comercials a Projects.

Configura variables sense publicar secrets

L’exemple utilitza VITE_CONTACT_LABEL, una etiqueta incorporada al JavaScript durant la construcció. Les variables VITE_* són públiques: no hi posis contrasenyes, claus privades ni tokens d’administració. Canviar la variable requereix un altre build; els fitxers ja publicats no es modifiquen.

Comprova per què encara apareix el valor anterior

En el nostre assaig original de variables de Vite, vam construir una etiqueta amb el valor A i vam servir els mateixos fitxers des d’un procés amb el valor B. El navegador continuava mostrant A després de recarregar, i el hash del JavaScript no canviava. En reconstruir amb B van canviar tant l’etiqueta com el hash. Sense la variable, va aparèixer el text alternatiu previst.

Si veus el valor antic, comprova quina variable va rebre el procés de construcció i quin build publiques. Canviar només l’entorn del servidor que lliura els fitxers estàtics no reescriu el bundle. Aquest assaig local verifica una configuració estàtica de Vite; no demostra la propagació de variables del tauler de Hostbrid ni el comportament de SSR o d’una configuració carregada en temps d’execució.

Pots reproduir les tres construccions amb Node 22.23.3 i Chrome a macOS seguint el README del repositori. Utilitza valors d’exemple públics: comprovar un sol marcador sense prefix en aquest assaig no constitueix una auditoria dels secrets del teu projecte.

Si el navegador encara crida localhost

Recarrega la web publicada a Network i obre la petició que falla. Una URL com http://localhost:3000/api/contact fa que el navegador del visitant intenti contactar amb el seu propi ordinador. Publicar els fitxers de React no publica automàticament aquest servidor.

Localitza on es construeix la URL: codi, configuració o una variable pública del build. Substitueix-la per l’endpoint HTTPS d’un backend que hagis publicat realment. Si fas servir una variable VITE_, torna a construir i publicar; canviar una variable després no modifica el JavaScript ja generat. No hi posis credencials privades.

Una referència relativa /api/contact evita fixar el hostname, però demana aquesta ruta al mateix origen que serveix la web. Fes-la servir només si hi ha el backend o un proxy configurat. Un 404 o l’HTML de la portada indica que encara cal revisar la ruta; no demostra un enviament correcte.

No substitueixis totes les aparicions de 0.0.0.0: pot ser l’adreça correcta on escolta un servidor. La URL que demana el navegador necessita la destinació pública. Després, recarrega i verifica URL, resposta i acció esperada. Corregir el hostname no verifica per si sol CORS, login ni recepció de formularis.

Verifica la web publicada

Obre l’URL HTTPS des d’un altre dispositiu. Visita la portada, escriu /about directament i recarrega. Comprova la imatge, els estils i el contingut de la segona ruta. Demanar un JavaScript inexistent ha de produir 404, no HTML amb estat 200.

Prova del 8 d’octubre de 2026: vam publicar el commit db329ae mitjançant el procés de construcció de Projects. La portada i /about retornen 200; CSS i JavaScript se serveixen amb els tipus de contingut correctes. Chrome va executar React a /about i va mostrar l’etiqueta pública del build. Els recursos absents i el marcador van retornar 404. La configuració de rutes es va provar a les dues rèpliques d’allotjament, incloent-hi llocs que no activen el fallback.

La prova utilitza un projecte propi de Hostbrid: verifica construcció i publicació, però no l’alta d’un client, la seva autorització OAuth ni els desplegaments automàtics en fer push. Consulta Projects i els plans vigents per triar capacitat. Si la web necessita un backend, decideix on s’executarà i prova’l abans d’oferir l’aplicació als usuaris.

Consulta també la documentació de construcció de Vite i les seves variables d’entorn públiques.

Si el repositori conté dues aplicacions i un paquet compartit, revisa el diagnòstic de npm workspaces abans de retallar una carpeta: l’arrel d’instal·lació i la sortida publicada tenen funcions diferents.