TypeScript

Astro는 TypeScript를 기본적으로 지원합니다. Astro 프로젝트에서 .ts 및 .tsx 파일을 가져오고, Astro 컴포넌트에 직접 TypeScript 코드를 작성할 수 있으며, 원하는 경우 Astro 구성에 astro.config.ts 파일을 사용할 수도 있습니다.

TypeScript를 사용하면 코드에서 객체 및 컴포넌트의 형태를 정의하여 런타임 시 오류를 방지할 수 있습니다. 예를 들어 TypeScript를 사용하여 컴포넌트의 props에 타입을 지정하면 컴포넌트가 허용하지 않는 prop을 설정할 경우 편집기에서 오류가 발생합니다.

Astro 프로젝트에서 TypeScript 코드를 작성하지 않아도 이점을 누릴 수 있습니다. Astro는 항상 컴포넌트 코드를 TypeScript로 처리하며, Astro VS Code 확장 프로그램은 자동 완성, 힌트 및 편집기 오류를 제공하기 위해 최대한 많은 정보를 추론합니다.

Astro 개발 서버는 타입 검사를 수행하지 않지만, 별도의 스크립트를 사용하여 명령줄에서 타입 오류를 검사할 수 있습니다.

설정

섹션 제목: 설정

Astro 시작 프로젝트에는 tsconfig.json 파일이 포함되어 있습니다. TypeScript 코드를 작성하지 않더라도 Astro 및 VS Code와 같은 도구가 프로젝트를 이해하는 방법을 알 수 있도록 하므로 이 파일은 중요합니다. tsconfig.json 파일이 없으면 일부 기능 (예: npm 패키지 가져오기)이 편집기에서 완전히 지원되지 않습니다. Astro를 수동으로 설치하는 경우 이 파일을 직접 만들어야 합니다.

TSConfig 템플릿

섹션 제목: TSConfig 템플릿

Astro에는 확장 가능한 세 가지 tsconfig.json 템플릿인 base, strict 및 strictest가 포함되어 있습니다. base 템플릿은 최신 JavaScript 기능에 대한 지원을 활성화하며 다른 템플릿의 기반으로도 사용됩니다. 프로젝트에서 TypeScript를 작성하려는 경우 strict 또는 strictest를 사용하는 것이 좋습니다. astro/tsconfigs/에서 세 가지 템플릿 구성을 보고 비교할 수 있습니다.

템플릿 중 하나를 상속하려면 extends 설정을 사용하세요.

tsconfig.json

{
  "extends": "astro/tsconfigs/base"
}

또한 Astro 타입을 활용하고 빌드된 파일의 검사를 피하기 위해 다음과 같이 include 및 exclude를 설정하는 것이 좋습니다.

tsconfig.json

{
  "extends": "astro/tsconfigs/base",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

src/env.d.ts 파일은 사용자 정의 타입 선언을 추가하기 위한 관례로서, 또는 tsconfig.json이 없는 경우 Astro 타입을 활용하기 위해 생성할 수 있습니다.

사용자 정의 타입 선언을 추가하거나 tsconfig.json이 없는 경우 Astro 타입을 활용하기 위해 src/env.d.ts를 규칙으로 생성할 수 있습니다.

src/env.d.ts

// 사용자 정의 타입을 선언합니다.
declare var myString: string;

// Astro 타입입니다. `tsconfig.json`이 이미 있는 경우에는 필요하지 않습니다.
/// <reference path="../.astro/types.d.ts" />

TypeScript 편집기 플러그인

섹션 제목: TypeScript 편집기 플러그인

공식 Astro VS Code 확장 프로그램을 사용하지 않을 때 Astro TypeScript 플러그인을 별도로 설치할 수 있습니다. 이 플러그인은 VSCode 확장 프로그램에 의해 자동으로 설치 및 구성되므로 둘 다 설치할 필요는 없습니다.

이 플러그인은 편집기에서만 실행됩니다. 터미널에서 tsc를 실행하면 .astro 파일은 완전히 무시됩니다. 대신 astro check CLI 명령을 사용하여 .astro 및 .ts 파일을 모두 검사할 수 있습니다.

이 플러그인은 .ts 파일에서 .astro 파일을 가져오는 것도 지원합니다 (다시 내보내기에 유용할 수 있음).

npm

npm install @astrojs/ts-plugin

pnpm

pnpm add @astrojs/ts-plugin

Yarn

yarn add @astrojs/ts-plugin

그런 다음 tsconfig.json에 다음을 추가하세요.

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@astrojs/ts-plugin"
      },
    ],
  }
}

플러그인이 작동하는지 확인하려면 .ts 파일을 만들고 Astro 컴포넌트를 가져옵니다. 편집기에서 경고 메시지가 표시되지 않아야 합니다.

UI 프레임워크

섹션 제목: UI 프레임워크

프로젝트에서 UI 프레임워크를 사용하는 경우 프레임워크에 따라 추가 설정이 필요할 수 있습니다. 자세한 내용은 프레임워크의 TypeScript 문서를 참조하세요. (Vue, React, Preact, Solid)

타입 가져오기

섹션 제목: 타입 가져오기

가능하면 명시적 타입 가져오기 및 내보내기를 사용하세요.

import { SomeType } from "./script";
import type { SomeType } from "./script";

이렇게 하면 Astro의 번들러가 가져온 타입을 JavaScript인 것처럼 잘못 번들링하려고 시도하는 엣지 케이스를 방지할 수 있습니다.

tsconfig.json 파일에서 타입 가져오기를 적용하도록 TypeScript를 구성할 수 있습니다. verbatimModuleSyntax를 true로 설정하세요. TypeScript는 가져오기를 확인하고 import type을 사용해야 하는 시점을 알려줍니다. 이 설정은 모든 프리셋에서 기본적으로 활성화되어 있습니다.

tsconfig.json

{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

별칭 가져오기

섹션 제목: 별칭 가져오기

Astro는 tsconfig.json paths 구성에서 정의하는 별칭 가져오기를 지원합니다. 자세한 내용은 가이드를 참조하세요.

src/pages/about/nate.astro

---
import HelloWorld from "@components/HelloWorld.astro";
import Layout from "@layouts/Layout.astro";
---

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  }
}

window 및 globalThis 확장

섹션 제목: window 및 globalThis 확장

전역 객체에 속성을 추가하려는 경우가 있을 수 있습니다. env.d.ts 파일에 declare 키워드를 사용하여 최상위 선언을 추가하면 됩니다.

src/env.d.ts

declare var myString: string;
declare function myFunction(): boolean;

이렇게 하면 window.myString 및 window.myFunction뿐만 아니라 globalThis.myString 및 globalThis.myFunction에 타입이 제공됩니다.

window는 클라이언트 측 코드에서만 사용할 수 있습니다. globalThis는 서버 측과 클라이언트 측 모두에서 사용할 수 있지만, 서버 측 값은 클라이언트와 공유되지 않습니다.

window 객체의 속성에만 타입을 추가하려면 Window 인터페이스를 사용하세요.

window 객체의 속성에만 타입을 지정하려면 대신 Window 인터페이스를 제공하세요.

src/env.d.ts

interface Window {
  myFunction(): boolean;
}

컴포넌트 Props

섹션 제목: 컴포넌트 Props

Astro는 TypeScript를 통해 컴포넌트 props의 타입을 지원합니다. 활성화하려면 컴포넌트 프런트매터에 TypeScript Props 인터페이스를 추가하세요. export 구문을 사용할 수 있지만 필수는 아닙니다. Astro VSCode 확장 프로그램은 Props 인터페이스를 자동으로 찾아서 다른 템플릿에서 해당 컴포넌트를 사용할 때 적절한 TS 지원을 제공합니다.

src/components/HelloProps.astro

---
interface Props {
  name: string;
  greeting?: string;
}
const { greeting = "Hello", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

일반적인 prop 타입 패턴

섹션 제목: 일반적인 prop 타입 패턴

• 컴포넌트가 props 또는 슬롯 콘텐츠를 사용하지 않는 경우 type Props = Record<string, never>를 사용할 수 있습니다.
• 컴포넌트의 기본 슬롯에 자식을 전달해야 하는 경우 type Props = { children: any; };를 사용하여 이를 적용할 수 있습니다.

타입 유틸리티

섹션 제목: 타입 유틸리티

추가된 버전: astro@1.6.0

Astro는 일반적인 prop 타입 패턴을 위한 몇 가지 내장 유틸리티 타입을 제공합니다. 이러한 타입은 astro/types 진입점에서 사용할 수 있습니다.

내장 HTML 속성

섹션 제목: 내장 HTML 속성

Astro는 마크업이 유효한 HTML 속성을 사용하고 있는지 검사하기 위한 HTMLAttributes 타입을 제공합니다. 이러한 타입을 사용하여 컴포넌트 props를 빌드할 수 있습니다.

예를 들어 <Link> 컴포넌트를 빌드하는 경우 컴포넌트의 prop 타입에서 <a> 태그에 대한 기본 HTML 속성을 미러링하기 위해 다음을 수행할 수 있습니다.

src/components/Link.astro

---
import type { HTMLAttributes } from "astro/types";

// `type`을 사용합니다.
type Props = HTMLAttributes<"a">;

// 또는 `interface`를 사용하여 확장합니다.
interface Props extends HTMLAttributes<"a"> {
  myProp?: boolean;
}

const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>

.d.ts 파일에서 astroHTML.JSX 네임스페이스를 다시 선언하여 기본 JSX 정의를 확장할 수 있습니다. 이를 통해 비표준 속성을 추가할 수도 있습니다.

src/custom-attributes.d.ts

declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    "data-count"?: number;
    "data-label"?: string;
  }

  // 스타일 객체에 CSS 사용자 정의 속성을 추가합니다.
  interface CSSProperties {
    "--theme-color"?: "black" | "white";
  }
}

노트

astroHTML은 .astro 컴포넌트에 전역적으로 주입됩니다. TypeScript 파일에서 사용하려면 삼중 슬래시 지시어를 사용하세요.

/// <reference types="astro/astro-jsx" />

type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;

ComponentProps 타입

섹션 제목: ComponentProps 타입

추가된 버전: astro@4.3.0

이 타입 내보내기를 사용하면 다른 컴포넌트가 Props 타입을 직접 내보내지 않더라도 해당 컴포넌트에서 허용하는 Props를 참조할 수 있습니다.

다음 예제는 <Button /> 컴포넌트의 Props 타입을 참조하기 위해 astro/types의 ComponentProps 유틸리티를 사용하는 방법을 보여줍니다.

src/pages/index.astro

---
import type { ComponentProps } from "astro/types";
import Button from "./Button.astro";

type ButtonProps = ComponentProps<typeof Button>;
---

다형적 타입

섹션 제목: 다형적 타입

추가된 버전: astro@2.5.0

Astro에는 다양한 HTML 요소로 렌더링할 수 있는 컴포넌트를 완전한 타입 안전성을 갖춰 더 쉽게 빌드할 수 있도록 도와주는 도우미가 포함되어 있습니다. 이는 전달된 props에 따라 <a> 또는 <button>으로 렌더링할 수 있는 <Link>와 같은 컴포넌트에 유용합니다.

아래 예제는 모든 HTML 요소로 렌더링할 수 있는 완전한 타입의 다형적 컴포넌트를 구현합니다. as prop이 유효한 HTML 요소인지 확인하기 위해 HTMLTag 타입이 사용됩니다.

---
import type { HTMLTag, Polymorphic } from "astro/types";

type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }>;

const { as: Tag, ...props } = Astro.props;
---
<Tag {...props} />

getStaticPaths() 타입 추론

섹션 제목: getStaticPaths() 타입 추론

추가된 버전: astro@2.1.0

Astro는 동적 라우트를 위한 getStaticPaths() 함수에서 반환된 타입을 처리하는 도우미를 포함합니다.

InferGetStaticParamsType으로 Astro.params의 타입을 얻고, InferGetStaticPropsType으로 Astro.props의 타입을 얻을 수 있습니다. 또는 GetStaticPaths를 사용하여 두 타입을 모두 얻을 수 있습니다.

src/pages/posts/[...id].astro

---
import type {
  InferGetStaticParamsType,
  InferGetStaticPropsType,
  GetStaticPaths,
} from "astro";

export const getStaticPaths = (async () => {
  const posts = await getCollection("blog");
  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { draft: post.data.draft, title: post.data.title },
    };
  });
}) satisfies GetStaticPaths;

type Params = InferGetStaticParamsType<typeof getStaticPaths>;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { id } = Astro.params as Params;
//                   ^? { id: string; }

const { title } = Astro.props;
//                      ^? { draft: boolean; title: string; }
---

타입 검사

섹션 제목: 타입 검사

편집기에서 타입 오류를 확인하려면 Astro VS Code 확장 프로그램이 설치되어 있는지 확인하세요. astro start 및 astro build 명령은 esbuild로 코드를 트랜스파일하지만 타입 검사를 실행하지는 않습니다. 코드에 TypeScript 오류가 포함된 경우 빌드되지 않도록 하려면 package.json의 “build” 스크립트를 다음과 같이 변경하세요.

package.json

{
  "scripts": {
    "build": "astro build",
    "build": "astro check && astro build",
  },
}

노트

astro check는 TypeScript 프로젝트에 포함된 모든 파일을 검사합니다. Svelte 및 Vue 파일의 타입을 검사하려면 각각 svelte-check 및 vue-tsc 패키지를 사용할 수 있습니다.

Astro에서 .ts 파일 가져오기에 대해 자세히 알아보세요.

TypeScript 구성에 대해 자세히 알아보세요.

문제 해결

섹션 제목: 문제 해결

동시에 여러 JSX 프레임워크의 타입 지정 시 오류 발생

섹션 제목: 동시에 여러 JSX 프레임워크의 타입 지정 시 오류 발생

동일한 프로젝트에서 여러 JSX 프레임워크를 사용하는 경우 문제가 발생할 수 있습니다. 각 프레임워크는 tsconfig.json에 서로 다른 설정, 때로는 충돌하는 설정이 필요하기 때문입니다.

해결: 사용하는 프레임워크에 맞게 jsxImportSource 설정을 react(기본값), preact 또는 solid-js로 설정합니다. 그리고 충돌하는 각각의 파일에 pragma 주석을 사용하세요.

해결 방법: 가장 많이 사용하는 프레임워크에 따라 jsxImportSource를 react (기본값), preact 또는 solid-js로 설정합니다. 그런 다음 다른 프레임워크의 충돌하는 파일에서 pragma 주석을 사용합니다.

jsxImportSource: react (기본 설정)의 경우 다음을 사용합니다.

// Preact
/** @jsxImportSource preact */

// Solid
/** @jsxImportSource solid-js */