본문으로 건너뛰기

처음부터 프로젝트를 빌드합니다

[!NOTE] 이미 CLI로 프로젝트를 만들었거나 시작하기 가이드의 예제를 복제해 프로젝트를 만들었다면, 이 가이드는 건너뛰고 라우팅 가이드로 넘어가면 됩니다.

TanStack Start 프로젝트를 처음부터 빌드하고 싶으신가요?

이 가이드는 매우 기본적인 TanStack Start 웹 애플리케이션을 만드는 데 도움이 됩니다. 함께 TanStack Start를 사용해 다음을 수행하겠습니다:

  • index page를 제공합니다
  • 카운터를 표시합니다
  • server와 client에서 카운터를 증가시킵니다

이렇게 표시됩니다

새 프로젝트 디렉터리를 만들고 초기화해 보겠습니다.

mkdir myApp
cd myApp
npm init -y

[!NOTE] 이 모든 예시에서는 npm을 사용하지만, 원하는 패키지 관리자를 대신 사용해도 됩니다.

TypeScript 설정​

TanStack Start와 함께 TypeScript를 사용하는 것을 강력히 권장합니다. 다음 설정을 최소한 포함하는 tsconfig.json 파일을 만듭니다:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true
  }
}

[!NOTE] verbatimModuleSyntax을 활성화하면 서버 번들이 클라이언트 번들에 누출될 수 있습니다. 이 옵션은 비활성화된 상태로 유지하는 것이 좋습니다.

의존성 설치​

TanStack Start는 TanStack Router를 기반으로 하며, 빌드 도구로 Vite 또는 Rsbuild를 지원합니다.

Start와 Router를 설치하려면 다음을 실행합니다:

npm i @tanstack/react-start @tanstack/react-router

React도 필요합니다:

npm i react react-dom

사용할 빌드 도구와 React 통합을 설치합니다:

Vite

npm i -D vite @vitejs/plugin-react

Rsbuild

npm i -D @rsbuild/core @rsbuild/plugin-react

Vite를 사용하는 경우, @vitejs/plugin-react 대신 @vitejs/plugin-react-swc도 사용할 수 있습니다.

그리고 TypeScript도 설치합니다:

npm i -D typescript @types/react @types/react-dom @types/node

설정 파일 업데이트​

그다음 package.json를 빌드 도구의 CLI를 사용하도록 업데이트하고 "type": "module"을 설정합니다:

Vite

{
  // ...
  "type": "module",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build"
  }
}

Rsbuild

{
  // ...
  "type": "module",
  "scripts": {
    "dev": "rsbuild dev",
    "build": "rsbuild build"
  }
}

그다음 TanStack Start의 빌드 도구 플러그인을 구성합니다:

Vite

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

export default defineConfig({
  server: {
    port: 3000,
  },
  resolve: {
    tsconfigPaths: true,
  },
  plugins: [
    tanstackStart(),
    // react's vite plugin must come after start's vite plugin
    viteReact(),
  ],
})

Rsbuild

rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [pluginReact(), tanstackStart()],
})

기본 템플릿 추가​

TanStack Start를 사용하려면 필수 파일이 2개 있습니다:

  1. 라우터 구성
  2. 애플리케이션의 루트

구성이 완료되면 다음과 같은 파일 트리가 됩니다:

.
├── src/
│   ├── routes/
│   │   └── `__root.tsx`
│   ├── `router.tsx`
│   ├── `routeTree.gen.ts`
├── `vite.config.ts` or `rsbuild.config.ts`
├── `package.json`
└── `tsconfig.json`

라우터 구성​

이 파일이 Start 안에서 사용되는 TanStack Router의 동작을 결정합니다. 여기에서는 기본 프리로딩 기능부터 캐시 stale 상태까지 모든 것을 구성할 수 있습니다.

[!NOTE] 아직 routeTree.gen.ts 파일은 없습니다. 이 파일은 TanStack Start를 처음 실행할 때 생성됩니다.

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
  })

  return router
}

애플리케이션의 루트​

마지막으로 애플리케이션의 루트를 만들어야 합니다. 이것이 다른 모든 라우트의 진입점입니다. 이 파일의 코드는 애플리케이션의 다른 모든 라우트를 감쌉니다.

// src/routes/__root.tsx
import type { ReactNode } from 'react'
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from '@tanstack/react-router'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      {
        charSet: 'utf-8',
      },
      {
        name: 'viewport',
        content: 'width=device-width, initial-scale=1',
      },
      {
        title: 'TanStack Start Starter',
      },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  )
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

첫 라우트 작성​

기본 템플릿 설정이 완료되었으므로 이제 첫 라우트를 작성할 수 있습니다. 이는 src/routes 디렉터리에 새 파일을 만들어서 수행합니다.

// src/routes/index.tsx
import * as fs from 'node:fs'
import { createFileRoute, useRouter } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'

const filePath = 'count.txt'

async function readCount() {
  return parseInt(
    await fs.promises.readFile(filePath, 'utf-8').catch(() => '0'),
  )
}

const getCount = createServerFn({
  method: 'GET',
}).handler(() => {
  return readCount()
})

const updateCount = createServerFn({ method: 'POST' })
  .validator((d: number) => d)
  .handler(async ({ data }) => {
    const count = await readCount()
    await fs.promises.writeFile(filePath, `${count + data}`)
  })

export const Route = createFileRoute('/')({
  component: Home,
  loader: async () => await getCount(),
})

function Home() {
  const router = useRouter()
  const state = Route.useLoaderData()

  return (
    <button
      type="button"
      onClick={() => {
        updateCount({ data: 1 }).then(() => {
          router.invalidate()
        })
      }}
    >
      Add 1 to {state}?
    </button>
  )
}

이제 끝입니다! 🤯 TanStack Start 프로젝트 설정을 마쳤고 첫 라우트도 작성했습니다. 🎉

이제 npm run dev를 실행하여 서버를 시작하고, http://localhost:3000로 이동해 라우트가 실제로 동작하는 모습을 볼 수 있습니다.

애플리케이션을 배포하고 싶으신가요? 호스팅 가이드를 확인하세요.