Blog · Guías de despliegue

Cómo desplegar una app TanStack Start en 2026: Nitro, un script start y un solo comando

Por el equipo de Pethost · 10 de octubre de 2026 · Actualizado 25 de octubre de 2026 · 9 min de lectura

Tienes una app TanStack Start y quieres ponerla en un servidor Node, en una dirección con HTTPS. La guía de hosting de TanStack le pide dos cosas a la app para eso: el plugin de Nitro y un script start. Con las dos en su sitio, pethost deploy escribe el Dockerfile, construye la app e imprime su dirección. La app que crea la CLI de TanStack se construyó e inició en 29 segundos la primera vez.

Qué necesitas para desplegar una app TanStack Start en 2026

Tres cosas: la app, el comando pethost y una cuenta de Pethost.

La app aquí es la que crea la CLI de TanStack, con Nitro como destino de despliegue:

npx @tanstack/cli@latest create my-app --deployment nitro

El flag agrega el plugin de Nitro a vite.config.ts. En una app que ya tienes, agrégalo como dice la parte de Nitro de la guía de hosting:

import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [tanstackStart(), nitro(), viteReact()],
})

Después dale a package.json el script que inicia lo que escribe el build. La CLI deja ahí build y ningún start:

"scripts": {
  "dev": "vite dev --port 3000",
  "build": "vite build",
  "start": "node .output/server/index.mjs"
}

El comando es un solo programa, que se instala con una línea. Todos sus comandos están en la referencia de la CLI.

curl -fsSL https://pethost.dev/install.sh | sh      # macOS, Linux
irm https://pethost.dev/install.ps1 | iex           # Windows, in PowerShell

La cuenta necesita un plan. Si no has iniciado sesión, pethost deploy abre tu navegador e inicia sesión por ti. Si aún no tienes plan, te muestra dónde elegir uno, y espera.

Despliega la app TanStack Start con un comando

Ve a la carpeta que tiene package.json y ejecuta pethost deploy. Esta es la pantalla entera, para la app que creó la CLI:

$ cd my-app
$ pethost deploy
Name it [my-app]:    it will live at https://my-app.sam.pethost.app
✓ Packed 18 files, 183 KB   (left out node_modules)
✓ Uploaded straight to your machine
✗ /compose.yaml: the project directory has no compose.yaml at its root: add one
✓ Node.js project detected, wrote Dockerfile.
✓ Packed 19 files, 184 KB   (left out node_modules)
✓ Uploaded straight to your machine
✓ Built and started in 29 s
  · wrote compose.yaml for the Dockerfile: the service app, reading .env
✓ app listens on 3000 → https://my-app.sam.pethost.app
  It answers 200.

https://my-app.sam.pethost.app

Wrote .pethost (commit it). Next:   pethost logs -f   ·   pethost open

1. Pregunta una sola cosa El nombre del proyecto, que es la primera palabra de su dirección. Con Enter se queda el nombre de la carpeta.
2. La máquina no encuentra nada que ejecutar La carpeta va directo a tu máquina, sin node_modules. La línea con la cruz es su respuesta: un proyecto se ejecuta desde un Dockerfile o un archivo de Compose, y la carpeta aún no tiene ninguno de los dos.
3. pethost escribe el Dockerfile Leyó los scripts build y start de package.json, y vuelve a subir la carpeta.
4. La máquina la construye y la inicia Ve que el servidor escucha en el 3000 y envía la dirección ahí. Después pethost visita la dirección él mismo e imprime lo que respondió: 200.

Le pedimos a la app desplegada lo que pide un visitante. La página principal y /about respondieron cada una 200 con HTML renderizado en el servidor, y una dirección sin ruta respondió 404. El servidor en ejecución ocupó 43 MB de memoria.

El Dockerfile que pethost escribe para TanStack Start

Este es el archivo tal como se escribió en la carpeta de la app, entero:

# Written by pethost deploy for this Node.js project: Node 24 (no .nvmrc names another),
# npm installs it (package-lock.json), package.json builds it with "vite build",
# package.json starts it with "node .output/server/index.mjs".
# It is yours now: change it as you like. pethost does not write it again.

FROM node:24
WORKDIR /app

COPY . .

# Every dependency: what builds the project, and may start it, is among the ones for
# development.
RUN --mount=type=cache,target=/root/.npm \
    npm install

RUN npm run build

ENV NODE_ENV=production
CMD ["npm", "run", "start"]

Sus primeras líneas dicen lo que pethost leyó en tu carpeta. El gestor de paquetes es el que nombra tu lockfile, y la versión de Node es la que nombra .nvmrc o .node-version, o Node 24 si no hay ninguno de los dos. El build y el inicio son tus dos scripts, tal como los escribiste.

Sin el script start

Una app TanStack Start se puede construir para varios tipos de proveedor de hosting, así que pethost no adivina cómo se inicia la tuya. Sin un script start no escribe ningún archivo y dice por qué:

$ pethost deploy
Name it [my-app]:    it will live at https://my-app.sam.pethost.app
✓ Packed 13 files, 177 KB
✓ Uploaded straight to your machine
✗ /compose.yaml: the project directory has no compose.yaml at its root: add one
  package.json builds the project and names nothing that starts it (no start script), and what it builds is no site of a kind pethost has a row for.
  Your coding agent writes one in a minute: "Write a Dockerfile for this app".
  Then run pethost deploy again.     How Pethost runs a folder: https://pethost.dev/docs/api/#CreateProject

Agrega el script y vuelve a ejecutar el comando.

Cambia una ruta y vuelve a desplegar

Edita una ruta y ejecuta el mismo comando. El segundo despliegue tardó 7 segundos, porque la máquina conserva las capas del build y la caché de npm:

$ pethost deploy
my-app (.pethost)
✓ Packed 20 files · uploaded · built and started in 7 s
  · wrote compose.yaml for the Dockerfile: the service app, reading .env
  · kept the project's x-pethost
  It answers 200.
https://my-app.sam.pethost.app

Cuando el build falla

Rompimos un archivo de ruta para verlo. La pantalla muestra el log del build con el error dentro, y la última línea dice qué reciben los visitantes. Esta es esa pantalla, recortada a tres de sus líneas:

$ pethost deploy
my-app (.pethost)
✗ Deploy failed: failed to build: failed to solve: process "/bin/sh -c npm run build" did not complete successfully: exit code: 1
    #9 0.793 Error: Error transforming route file /app/src/routes/about.tsx: SyntaxError: Unexpected token, expected "," (4:19)
  Nothing changed: the version before still runs.

Para desplegar con cada push, conecta el repositorio una vez con pethost github sam/my-app. Pethost lee solo los repositorios que le diste a su GitHub App. pethost rollback vuelve a poner la versión anterior a la actual, y tu máquina conserva las tres versiones anteriores a ella. Un agente de IA puede hacer todo esto por ti a través del servidor MCP de Pethost: cómo un agente despliega y cuida un proyecto.

Variables de entorno y tu propio dominio

Una variable que lee una server function es un comando. Pide el valor sin mostrarlo, lo pone en el archivo .env del proyecto en la máquina, y los despliegues siguientes la conservan:

pethost env set DATABASE_URL

Cualquier nombre bajo el dominio de tu cuenta es una dirección desde el primer momento, con HTTPS. Un dominio tuyo lleva un comando y un registro DNS:

pethost domain add app.example.com

El comando imprime el registro que hay que crear: un CNAME de tu nombre al nombre de tu máquina. El certificado llega solo en cuanto el nombre resuelve, y se renueva solo.

Qué obtienes por el precio

Pethost cuesta 9,99 € al mes por todo lo que alojas, con 2 vCPU, 3 GB de memoria y 30 GB de disco. El servidor de la app ocupó 43 MB de esa memoria, así que en la máquina queda sitio para su base de datos, un worker y tus otros proyectos, como una app React Router a su lado. No pagas por proyecto y nada se mide por uso: las server functions no se cobran por llamada.

• 9,99 € al mes por todos tus proyectos, nada se mide por uso
• 29 s para construir e iniciar la app, la primera vez
• 7 s para el despliegue siguiente

Lo que ya está hecho por ti: HTTPS con certificados que se renuevan solos, despliegues desde GitHub, backups cada noche conservados 14 días, SSH a cualquier contenedor y cada petición contada, con los paths más visitados y la tasa de errores de los últimos 30 días. La máquina está siempre encendida, así que una server function nunca espera a un arranque en frío. Los planes están en la parte de precios de la página principal.

Las pantallas son despliegues de la app que escribe npx @tanstack/cli@latest create --deployment nitro, con TanStack Start 1.168.61, Nitro 3.0.260610-beta y pethost 0.2.1, en una máquina de prueba nuestra que no había construido nada antes. La cuenta que aparece en ellas es la de ejemplo, sam.

1. TanStack Start: hosting
2. TanStack Start: inicio rápido
3. pethost, la línea de comandos de Pethost