Nota

Você não precisa do bun create para usar o Bun. Você não precisa de nenhuma configuração. Este comando existe para tornar o início um pouco mais rápido e fácil.

---

Crie um novo projeto Bun com bun create. Este é um comando flexível que pode ser usado para criar um novo projeto a partir de um componente React, um pacote npm create-<template>, um repositório GitHub, ou um template local.

Se você está procurando criar um novo projeto vazio, use bun init.

A partir de um componente React

bun create ./MyComponent.tsx transforma um componente React existente em um ambiente de desenvolvimento completo com hot reload e builds de produção em um único comando.

$ bun create ./MyComponent.jsx # .tsx também suportado

Nota

🚀 Sucessor do Create React App — bun create <component> fornece tudo que os desenvolvedores amavam no Create React App, mas com ferramentas modernas, builds mais rápidos e suporte backend.

Como isto funciona

Quando você roda bun create <component>, o Bun:

1. Usa o bundler JavaScript do Bun para analisar seu grafo de módulos.
2. Coleta todas as dependências necessárias para rodar o componente.
3. Escaneia as exportações do entry point por um componente React.
4. Gera um arquivo package.json com as dependências e scripts necessários para rodar o componente.
5. Instala quaisquer dependências faltando usando bun install --only-missing.
6. Gera os seguintes arquivos:
   • ${component}.html
   • ${component}.client.tsx (entry point para o frontend)
   • ${component}.css (arquivo css)
7. Inicia um servidor de desenvolvimento frontend automaticamente.

Usando TailwindCSS com Bun

TailwindCSS é um framework CSS utility-first extremamente popular usado para estilizar aplicações web.

Quando você roda bun create <component>, o Bun escaneia seu arquivo JSX/TSX por nomes de classe TailwindCSS (e quaisquer arquivos que importa). Se detectar nomes de classe TailwindCSS, adicionará as seguintes dependências ao seu package.json:

{
  "dependencies": {
    "tailwindcss": "^4",
    "bun-plugin-tailwind": "latest"
  }
}

Também configuramos bunfig.toml para usar o plugin TailwindCSS do Bun com Bun.serve()

[serve.static]
plugins = ["bun-plugin-tailwind"]

E um arquivo ${component}.css com @import "tailwindcss"; no topo:

@import "tailwindcss";

Usando shadcn/ui com Bun

shadcn/ui é uma ferramenta de biblioteca de componentes extremamente popular para construir aplicações web.

bun create <component> escaneia por quaisquer componentes shadcn/ui importados de @/components/ui.

Se encontrar algum, roda:

# Assumindo que bun detectou imports para @/components/ui/accordion e @/components/ui/button
bunx shadcn@canary add accordion button # e quaisquer outros componentes

Como shadcn/ui usa TailwindCSS, bun create também adiciona as dependências TailwindCSS necessárias ao seu package.json e configura bunfig.toml para usar o plugin TailwindCSS do Bun com Bun.serve() conforme descrito acima.

Adicionalmente, configuramos o seguinte:

• tsconfig.json para alias "@/*" para "src/*" ou . (dependendo se existe um diretório src/)
• components.json para que shadcn/ui saiba que é um projeto shadcn/ui
• arquivo styles/globals.css que configura Tailwind v4 da maneira que shadcn/ui espera
• arquivo ${component}.build.ts que builda o componente para produção com bun-plugin-tailwind configurado

bun create ./MyComponent.jsx é uma das maneiras mais fáceis de rodar código gerado por LLMs como Claude ou ChatGPT localmente.

A partir do npm

bun create <template> [<destination>]

Assumindo que você não tem um template local com o mesmo nome, este comando irá baixar e executar o pacote create-<template> do npm. Os seguintes dois comandos se comportarão identicamente:

bun create remix
bunx create-remix

Consulte a documentação do pacote create-<template> associado para documentação completa e instruções de uso.

A partir do GitHub

Isto baixará o conteúdo do repositório GitHub para o disco.

bun create <user>/<repo>
bun create github.com/<user>/<repo>

Opcionalmente especifique um nome para a pasta de destino. Se nenhum destino for especificado, o nome do repo será usado.

bun create <user>/<repo> mydir
bun create github.com/<user>/<repo> mydir

O Bun executará os seguintes passos:

• Baixar o template
• Copiar todos os arquivos do template para a pasta de destino
• Instalar dependências com bun install.
• Inicializar um repositório Git fresco. Opt out com a flag --no-git.
• Rodar o script start configurado do template, se definido.

NOTE

Por padrão o Bun _não sobrescreverá_ quaisquer arquivos existentes. Use a flag `--force` para sobrescrever arquivos existentes.

A partir de um template local

Aviso

Ao contrário de templates remotos, rodar bun create com um template local deletará toda a pasta de destino se ela já existir! Tenha cuidado.

O templater do Bun pode ser estendido para suportar templates customizados definidos no seu sistema de arquivos local. Estes templates devem viver em um dos seguintes diretórios:

• $HOME/.bun-create/<name>: templates globais
• <project root>/.bun-create/<name>: templates específicos do projeto

Nota

Você pode customizar o caminho do template global definindo a variável de ambiente BUN_CREATE_DIR.

Para criar um template local, navegue até $HOME/.bun-create e crie um novo diretório com o nome desejado do seu template.

cd $HOME/.bun-create
mkdir foo
cd foo

Então, crie um arquivo package.json naquele diretório com o seguinte conteúdo:

{
  "name": "foo"
}

Você pode rodar bun create foo em outro lugar no seu sistema de arquivos para verificar que o Bun está encontrando corretamente seu template local.

Setup de lógica

Você pode especificar scripts de setup pré e pós-instalação na seção "bun-create" do package.json do seu template local.

{
  "name": "@bun-examples/simplereact",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "bun-create": {
    "preinstall": "echo 'Installing...'", // um único comando
    "postinstall": ["echo 'Done!"], // um array de comandos
    "start": "bun run echo 'Hello world!'"
  }
}

Os seguintes campos são suportados. Cada um destes pode corresponder a uma string ou array de strings. Um array de comandos será executado em ordem.

Campo	Descrição
postinstall	roda após instalar dependências
preinstall	roda antes de instalar dependências

Após clonar um template, bun create automaticamente removerá a seção "bun-create" do package.json antes de escrever para a pasta de destino.

Referência

Flags CLI

Flag	Descrição
--force	Sobrescrever arquivos existentes
--no-install	Pular instalação de node_modules e tarefas
--no-git	Não inicializar um repositório git
--open	Iniciar e abrir no navegador após terminar

Variáveis de ambiente

Nome	Descrição
GITHUB_API_DOMAIN	Se você está usando um GitHub enterprise ou um proxy, você pode customizar o domínio GitHub que o Bun acessa para downloads
GITHUB_TOKEN (ou GITHUB_ACCESS_TOKEN)	Isto permite que bun create funcione com repositórios privados ou se você for limitado por rate. GITHUB_TOKEN é escolhido sobre GITHUB_ACCESS_TOKEN se ambos existirem.

Como bun create funciona

Quando você roda bun create ${template} ${destination}, eis o que acontece:

SE template remoto

1. GET registry.npmjs.org/@bun-examples/${template}/latest e parseia
2. GET registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz
3. Descomprime e extrai ${template}-${latestVersion}.tgz para ${destination}
   • Se houver arquivos que sobrescreveriam, avisa e sai a menos que --force seja passado

SE repositório GitHub

1. Baixa o tarball da API do GitHub
2. Descomprime e extrai para ${destination}
   • Se houver arquivos que sobrescreveriam, avisa e sai a menos que --force seja passado

SENÃO SE template local

1. Abre pasta do template local

2. Deleta diretório de destino recursivamente

3. Copia arquivos recursivamente usando as system calls mais rápidas disponíveis (no macOS fcopyfile e Linux, copy_file_range). Não copia ou atravessa pasta node_modules se existir (isto sozinho torna mais rápido que cp)

4. Parseia o package.json (novamente!), atualiza name para ser ${basename(destination)}, remove a seção bun-create do package.json e salva o package.json atualizado em disco.

   • SE Next.js for detectado, adiciona bun-framework-next à lista de dependências
   • SE Create React App for detectado, adiciona o entry point em /src/index.{js,jsx,ts,tsx} para public/index.html
   • SE Relay for detectado, adiciona bun-macro-relay para que Relay funcione

5. Auto-detecta o cliente npm, preferindo pnpm, yarn (v1), e por último npm

6. Roda quaisquer tarefas definidas em "bun-create": { "preinstall" } com o cliente npm

7. Roda ${npmClient} install a menos que --no-install seja passado OU não haja dependências no package.json

8. Roda quaisquer tarefas definidas em "bun-create": { "postinstall" } com o cliente npm

9. Roda git init; git add -A .; git commit -am "Initial Commit";

   • Renomeia gitignore para .gitignore. NPM automaticamente remove arquivos .gitignore de aparecer em pacotes.
   • Se houver dependências, isto roda em uma thread separada concorrentemente enquanto node_modules estão sendo instalados
   • Usar libgit2 se disponível foi testado e teve performance 3x pior em microbenchmarks