본문으로 건너뛰기

처음부터 프로젝트 빌드하기

[!NOTE] CLI로 프로젝트를 이미 생성했거나 시작하기 가이드의 예제를 복제했다면, 이 가이드를 건너뛰고 라우팅 가이드로 이동할 수 있습니다.

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

이 가이드에서는 매우 기본적인 TanStack Start 웹 애플리케이션을 빌드하는 방법을 안내합니다. TanStack Start를 사용하여 다음 작업을 함께 진행합니다:

  • 인덱스 페이지 제공
  • 카운터 표시
  • 서버와 클라이언트에서 카운터 증가

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

mkdir myApp
cd myApp
npm init -y

[!NOTE] 이 모든 예제에서는 npm을 사용하지만, 원하는 패키지 관리자를 대신 사용할 수 있습니다.

TypeScript 구성​

TanStack Start와 함께 TypeScript를 사용할 것을 적극 권장합니다. 최소한 다음 설정을 포함하는 tsconfig.json 파일을 생성합니다:

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "solid-js",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true
  }
}

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

의존성 설치​

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

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

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

SolidJS도 필요합니다:

npm i solid-js

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

Vite

npm i -D vite vite-plugin-solid

Rsbuild

npm i -D @rsbuild/core @rsbuild/plugin-babel @rsbuild/plugin-solid

그리고 TypeScript 관련 패키지도 설치합니다:

npm i -D typescript @types/node

구성 파일 업데이트​

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

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/solid-start/plugin/vite'
import viteSolid from 'vite-plugin-solid'

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

Rsbuild

rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginBabel } from '@rsbuild/plugin-babel'
import { pluginSolid } from '@rsbuild/plugin-solid'
import { tanstackStart } from '@tanstack/solid-start/plugin/rsbuild'

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
    }),
    pluginSolid(),
    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의 동작을 결정합니다. 여기에서 기본 사전 로딩 기능부터 캐시 유효 기간까지 모든 항목을 구성할 수 있습니다.

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

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

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

  return router
}

애플리케이션의 루트​

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

// src/routes/__root.tsx
import * as Solid from 'solid-js'
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from '@tanstack/solid-router'
import { HydrationScript } from 'solid-js/web'

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: Solid.JSX.Element }>) {
  return (
    <html>
      <head>
        <HydrationScript />
      </head>
      <body>
        <HeadContent />
        <Solid.Suspense>{children}</Solid.Suspense>
        <Scripts />
      </body>
    </html>
  )
}

첫 번째 라우트 작성​

이제 기본 템플릿 설정을 마쳤으므로 첫 번째 라우트를 작성할 수 있습니다. src/routes 디렉터리에 새 파일을 생성하면 됩니다.

import * as fs from 'node:fs'
import { createFileRoute, useRouter } from '@tanstack/solid-router'
import { createServerFn } from '@tanstack/solid-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로 이동하여 라우트가 작동하는 모습을 확인할 수 있습니다.

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