Blog · Guias de deploy

Como fazer deploy de um app TanStack Start em 2026: Nitro, um script start e um comando

Pela equipe da Pethost · 10 de outubro de 2026 · Atualizado em 25 de outubro de 2026 · 9 min de leitura

Você tem um app TanStack Start e quer colocá-lo em um servidor Node, em um endereço com HTTPS. O guia de hospedagem do TanStack pede duas coisas do app para isso: o plugin do Nitro e um script start. Com os dois no lugar, o pethost deploy escreve o Dockerfile, faz o build do app e mostra o endereço dele. O app que a CLI do TanStack cria teve o build feito e foi iniciado em 29 segundos na primeira vez.

O que você precisa para fazer deploy de um app TanStack Start em 2026

Três coisas: o app, o comando pethost e uma conta no Pethost.

O app aqui é o que a CLI do TanStack cria, com o Nitro como destino de deploy:

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

A flag adiciona o plugin do Nitro ao vite.config.ts. Em um app que você já tem, adicione-o como diz a parte do Nitro no guia de hospedagem:

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()],
})

Depois dê ao package.json o script que inicia o que o build escreve. A CLI deixa ali o build e nenhum start:

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

O comando é um programa, instalado com uma linha. Todos os comandos dele estão na referência da CLI.

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

A conta precisa de um plano. Se você não entrou, o pethost deploy abre o seu navegador e faz o seu login. Se você ainda não tem um plano, ele mostra onde escolher um e espera.

Faça o deploy do app TanStack Start com um comando

Vá até a pasta que tem o package.json e rode pethost deploy. Esta é a tela inteira, para o app que a CLI criou:

$ 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. Ele pergunta uma coisa O nome do projeto, que é a primeira palavra do endereço. Enter usa o nome da pasta.
2. A máquina não encontra nada para rodar A pasta vai direto para a sua máquina, sem o node_modules. A linha com o X é a resposta dela: um projeto roda a partir de um Dockerfile ou de um arquivo Compose, e a pasta ainda não tem nenhum dos dois.
3. O pethost escreve o Dockerfile Ele leu os scripts build e start do package.json, e envia a pasta de novo.
4. A máquina faz o build e o inicia Ela vê que o servidor escuta na 3000 e manda o endereço para lá. Depois o pethost acessa o próprio endereço e mostra o que ele respondeu: 200.

Pedimos ao app no ar o que um visitante pede. A página inicial e /about responderam 200 com HTML renderizado no servidor, e um endereço sem rota respondeu 404. O servidor rodando ocupou 43 MB de memória.

O Dockerfile que o pethost escreve para o TanStack Start

Este é o arquivo como foi escrito na pasta do app, inteiro:

# 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"]

As primeiras linhas dele dizem o que o pethost leu na sua pasta. O gerenciador de pacotes é o que o seu lockfile indica, e a versão do Node é a que o .nvmrc ou o .node-version indica, ou o Node 24 quando não há nenhum dos dois. O build e o start são os seus dois scripts, como você os escreveu.

Sem o script start

Um app TanStack Start pode ter o build feito para vários tipos de hospedagem, então o pethost não tenta adivinhar como o seu inicia. Sem um script start, ele não escreve nenhum arquivo e diz 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

Adicione o script e rode o comando de novo.

Altere uma rota e faça o deploy de novo

Edite uma rota e rode o mesmo comando. O segundo deploy levou 7 segundos, porque a máquina guarda as camadas do build e o cache do 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

Quando o build falha

Quebramos um arquivo de rota para ver isso. A tela mostra o log do build com o erro, e a última linha diz o que os visitantes recebem. Esta é essa tela, encurtada para três das suas linhas:

$ 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 fazer o deploy a cada push, conecte o repositório uma vez com pethost github sam/my-app. O Pethost lê só os repositórios que você deu ao GitHub App dele. O pethost rollback coloca de volta a versão anterior à atual, e a sua máquina guarda as três versões antes dela. Um agente de IA pode fazer tudo isso por você pelo servidor MCP do Pethost: como um agente faz o deploy de um projeto e cuida dele.

Variáveis de ambiente e seu próprio domínio

Uma variável que uma server function lê é um comando. Ele pede o valor sem mostrá-lo, coloca-o no arquivo .env do projeto na máquina, e os próximos deploys o mantêm:

pethost env set DATABASE_URL

Qualquer nome sob o domínio da sua conta já é um endereço na hora, com HTTPS. Um domínio seu leva um comando e um registro DNS:

pethost domain add app.example.com

O comando mostra o registro a criar: um CNAME do seu nome para o nome da sua máquina. O certificado chega sozinho assim que o nome resolve, e se renova sozinho.

O que você recebe pelo preço

O Pethost custa € 9,99 por mês por tudo o que você hospeda, com 2 vCPU, 3 GB de memória e 30 GB de disco. O servidor do app ocupou 43 MB dessa memória, então a máquina tem espaço para o banco de dados dele, um worker e os seus outros projetos, como um app React Router ao lado dele. Não há taxa por projeto e nada é medido: as server functions não são cobradas por chamada.

• € 9,99 por mês por todos os seus projetos, nada medido
• 29s para fazer o build e iniciar o app, na primeira vez
• 7s para o deploy seguinte

O que já vem feito para você: HTTPS com certificados que se renovam sozinhos, deploys a partir do GitHub, backups noturnos guardados por 14 dias, SSH em qualquer container, e cada requisição contada, com os caminhos mais acessados e a taxa de erros dos últimos 30 dias. A máquina está sempre ligada, então uma server function nunca espera um cold start. Os planos estão na parte de preços da página inicial.

As telas são deploys do app que o npx @tanstack/cli@latest create --deployment nitro escreve, com o TanStack Start 1.168.61, o Nitro 3.0.260610-beta e o pethost 0.2.1, em uma máquina de teste nossa que nunca tinha feito build de nada. A conta nelas é a de exemplo, sam.

1. TanStack Start: hospedagem
2. TanStack Start: quick start
3. pethost, a linha de comando do Pethost