타입스크립트(TypeScript)

타입스크립트(TypeScript)

Astro는 TypeScript를 내장 지원해요. 프로젝트에서 .ts·.tsx 파일을 import하고, Astro 컴포넌트 안에 직접 TypeScript 코드를 쓰고, astro.config.ts 파일을 쓸 수도 있어요. TypeScript로 객체·컴포넌트의 형태를 정의해 런타임 오류를 예방할 수 있어요.

출처: https://docs.astro.build/en/guides/typescript/

TypeScript를 쓰지 않아도 Astro 프로젝트에서 이점을 얻을 수 있어요. Astro는 컴포넌트 코드를 항상 TypeScript로 취급하고, Astro VS Code 확장이 가능한 한 코드를 추론해 자동완성·힌트·오류를 제공해요. Astro dev 서버는 타입 체크를 수행하지 않으므로, 별도 스크립트로 명령줄에서 타입 오류를 확인할 수 있어요.

설정

Astro 스타터 프로젝트는 tsconfig.json 파일을 포함해요. tsconfig.json 없이는 npm 패키지 import 같은 일부 기능이 에디터에서 완전히 지원되지 않으므로 이 파일이 중요해요.

TSConfig 템플릿

Astro에는 base, strict, strictest 세 개의 확장 가능한 tsconfig.json 템플릿이 있어요. base 템플릿은 최신 JavaScript 기능을 지원하고 다른 템플릿의 기초로 쓰여요. 프로젝트에서 TypeScript를 쓸 계획이라면 strict나 strictest를 권장해요.

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

TypeScript 에디터 플러그인

공식 Astro VS Code 확장을 쓰지 않을 때는 @astrojs/ts-plugin을 따로 설치할 수 있어요. 이 플러그인은 에디터에서만 실행되고, 터미널에서 tsc를 실행할 때 .astro 파일은 무시돼요. 대신 astro check CLI 명령으로 .astro와 .ts 파일을 둘 다 확인할 수 있어요.

Import 별칭(Import Aliases)

Astro는 tsconfig.json의 paths 구성에 정의한 import 별칭을 지원해요.

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

전역 타입 확장

src/env.d.ts 파일을 관례상 커스텀 타입 선언을 추가하거나 Astro 타입을 활용하는 데 쓸 수 있어요. window·globalThis에 타입을 제공하거나, astroHTML.JSX 네임스페이스를 재선언해서 비표준 속성이나 CSS 프로퍼티의 타입을 정의할 수도 있어요.

컴포넌트 Props

TypeScript Props 인터페이스를 컴포넌트 frontmatter에 추가해 컴포넌트 props를 타입 지정할 수 있어요. export 문은 선택 사항이에요. Astro VS Code 확장은 Props 인터페이스를 자동으로 찾아 다른 템플릿에서 그 컴포넌트를 쓸 때 TS 지원을 제공해요.

---
interface Props {
  name: string;
  greeting?: string;
}

const { greeting = "Hello", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

타입 유틸리티

Astro는 공통 prop 타입 패턴을 위한 내장 유틸리티 타입을 astro/types 엔트리포인트 아래에 제공해요.

  • HTMLAttributes — 마크업이 유효한 HTML 속성을 쓰는지 검사.
  • ComponentProps — 다른 컴포넌트가 받는 Props를 참조(해당 컴포넌트가 Props를 직접 export하지 않아도 됨).
  • Polymorphic/HTMLTag — as prop에 따라 <a>나 <button>처럼 다른 HTML 요소로 렌더링되는 컴포넌트를 타입 안전하게 제작.
  • InferGetStaticParamsType, InferGetStaticPropsType, GetStaticPaths — Astro.params·Astro.props의 타입 추론.

타입 체크

에디터에서 타입 오류를 보려면 Astro VS Code 확장을 설치하세요. astro start와 astro build는 esbuild로 코드를 트랜스파일하지만 타입 체크는 수행하지 않아요. 명령줄 타입 체크는 astro check를 쓰세요.

문제 해결

여러 JSX 프레임워크를 동시에 타입 지정할 때 오류가 나면, jsxImportSource를 가장 많이 쓰는 프레임워크(react 기본, preact, solid-js)에 맞추고, 다른 프레임워크의 충돌 파일 안에서 pragma 주석을 쓰세요.

// For Preact
/** @jsxImportSource preact */
// For Solid
/** @jsxImportSource solid-js */

더 알아보기