Astro v2로 업그레이드하기

이 가이드는 Astro v1에서 Astro v2로 마이그레이션하는 걸 도울 것입니다.

이전 프로젝트를 v1으로 업그레이드해야 하나요? older migration guide (EN)를 참조하세요.

Astro 업그레이드하기

패키지 관리자를 사용하여 프로젝트의 Astro 버전을 최신 버전으로 업데이트하세요. Astro 인터그레이션 기능을 사용 중인 경우 해당 기능도 최신 버전으로 업데이트하세요.

# Astro v2.x 설치하기
npm install astro@latest

# 예시: 최신 React, tailwind 설치하기.
npm install @astrojs/react@latest @astrojs/tailwind@latest

# Astro v2.x 설치하기
pnpm add astro@latest

# 예시: 최신 React, tailwind 설치하기.
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

# Astro v2.x 설치하기
yarn add astro@latest

# 예시: 최신 React, tailwind 설치하기.
yarn add @astrojs/react@latest @astrojs/tailwind@latest

Astro v2.0 중요한 변경 사항

Astro v2.0은 일부 중요한 변경 사항에는 지원 종료된 일부 기능이 제거되었습니다. v2.0으로 업그레이드한 후 프로젝트가 예상대로 작동하지 않으면, 이 가이드를 확인하여 모든 중요한 변경 사항을 확인하고 코드베이스를 업데이트하는 방법에 대해 확인해보세요.

자세한 내용은 패치노트를 통해 확인하실수 있습니다.

Node.js 14에 대한 지원 종료

Node.js 14는 2023년 4월에 수명이 종료될 예정입니다.

Astro v2.0은 Node.js의 최신 기능을 사용할 수 있게 Node.js 14에 대한 지원을 완전히 중단했습니다.

무엇을 해야 하나요?

개발 환경과 배포 환경 모두 Node.js 16.12.0 이상을 사용하고 있는지 확인합니다.

다음 명령어를 사용하여 Node.js 버전을 확인합니다
터미널 창
```
node -v
```
만약 로컬 개발 환경을 업그레이드해야 하는 경우, Node.js를 설치하세요.
Deployments environment의 문서를 확인하여 Node.js 16을 지원하는지 확인하세요.

대시보드 구성 설정 또는 .nvmrc 파일에서 Astro 프로젝트의 Node.js 버젼을 16.12.0으로 지정할 수 있습니다.

변경됨: `src/content/` 예약 폴더

이제 Astro v2.0에는 마크다운 및 MDX 파일을 content collections로 정리할 수 있는 컬렉션 API가 포함되어 있습니다. 이 API는 src/content/를 특수 폴더로 예약합니다.

무엇을 해야 하나요?

충돌을 피하기 위해 기존 src/content/ 폴더의 이름을 변경하세요. 이 폴더가 있는 경우 이제 이 폴더는 content collections에만 사용할 수 있습니다.

변경됨: `Astro.site`의 후행 슬래시

Astro v1.x에서 Astro는 Astro.site를 사용하여 액세스할 때 astro.config.mjs에서 site로 설정한 URL에 항상 후행 슬래시가 있는지 확인했습니다.

Astro v2.0은 더 이상 site의 값을 수정하지 않습니다. Astro.site는 정의되어있는 정확한 값을 사용하며, 원하는 경우 후행 슬래시를 추가해야합니다.

무엇을 해야 하나요?

astro.config.mjs에서 site에 설정된 URL에 후행 슬래시를 추가합니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  site: 'https://example.com/',
});

변경됨: `_astro/` 풀더 통합

v1.x에서는 에셋이 assets/, chunks/ 및 빌드 출력의 루트와 같은 다양한 위치에 빌드되었습니다.

Astro v2.0은 모든 빌드 출력 에셋을 새로운 _astro/ 폴더로 통합되었습니다.

디렉터리dist/
- 디렉터리_astro
  - client.9218e799.js
  - index.df3f880e0.css

이 위치는 새로운 build.assets 구성 옵션으로 제어할 수 있습니다.

무엇을 해야 하나요?

만약 배포 플렛폼이 이러한 애셋들의 위치에 의존한다면 배포 플렛폼의 설정을 바꾸세요.

변경됨: 마크다운 플러그인 설정

`extendDefaultPlugins` 삭제됨

v1.x에서 Astro는 사용자 고유의 마크다운 플러그인을 추가할 때 markdown.extendDefaultPlugins를 사용하여 Astro의 기본 플러그인을 다시 활성화했습니다.

이제 이 동작이 기본값이 되었기 때문에 Astro v2.0에서는 이 구성 옵션이 완전히 제거되었습니다.

마크다운 구성에서 remark 및 rehype 플러그인을 적용하면 더 이상 Astro의 기본 플러그인이 비활성화되지 않습니다. 이제 사용자 지정 remarkPlugins 또는 rehypePlugins 구성 여부에 관계없이 GitHub-Flavored Markdown 및 Smartypants가 적용됩니다.

무엇을 해야 하나요?

설정 파일에서 extendDefaultPlugins를 제거하세요. 이는 이제 v2.0에서 Astro의 기본 동작이며 이 줄은 대체할 필요 없이 삭제할 수 있습니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    extendDefaultPlugins,
  }
});

신기능: `gfm`과 `smartypants`

v1.x에서는 markdown.extendDefaultPlugins: false를 설정하여 Astro의 기본 마크다운 플러그인(GitHub-Flavored Markdown 및 SmartyPants)을 모두 비활성화하도록 선택할 수 있었습니다.

Astro v2.0에서는 markdown.extendDefaultPlugins: false를 별도의 boolean 옵션으로 대체하여 Astro에 내장된 각 기본 마크다운 플러그인을 개별적으로 제어할 수 있습니다. 이 옵션은 기본적으로 활성화되어 있으며 독립적으로 false로 설정할 수 있습니다.

무엇을 해야 하나요?

설정 파일에서 extendPlugins: 'markdown'을 삭제하세요. 이제부터는 기본값으로 설정됩니다.

markdown.gfm: false GitHub-Flavored Markdown를 비활성화하는 옵션
markdown.smartypants: false SmartyPants를 비활성화하는 옵션

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    extendDefaultPlugins: false,
    smartypants: false,
    gfm: false,
  }
});

변경됨: MDX 플러그인 설정

`extendPlugins` 문법이 `extendMarkdownConfig` 로 변경되었습니다.

v1.x에서 MDX Interaction이 extendPlugins 옵션은 MDX 파일이 Markdown 구성을 상속하는 방법을 관리합니다. Markdown 구성(markdown) 전체 또는 Astro의 기본 플러그인만(default) 상속하는 방법을 선택할 수 있었습니다.

Astro v2.0에서는 mdx.extendPlugins로 제어되던 동작을 세 개의 새로운, 독립적으로 구성 가능한 옵션으로 대체했습니다. 이 새로운 옵션은 기본적으로 true로 설정됩니다.

mdx.extendMarkdownConfig Markdown 구성 전체 또는 아무것도 상속하지 않도록 지정하는 옵션
mdx.gfm MDX에서 GitHub-Flavored Markdown을 활성화 또는 비활성화하는 옵션
mdx.smartypants MDX에서 SmartyPants를 활성화 또는 비활성화하는 옵션

무엇을 해야 하나요?

extendPlugins: 'markdown' 를 제거하세요. 이 동작은 이제 기본값입니다.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({
      extendPlugins: 'markdown',
    }),
  ],
});

extendPlugins: 'defaults'를 extendMarkdownConfig: false로 대체하고, MDX에서 기본 플러그인들을 개별적으로 활성화할 수 있도록 GitHub-Flavored Markdown과 SmartyPants 각각의 옵션을 추가하세요.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({
      extendPlugins: 'defaults',
      extendMarkdownConfig: false,
      smartypants: true,
      gfm: true,
    }),
  ],
});

Markdown과 일치하도록 더 많은 MDX 설정 옵션들이 추가되었습니다.

Astro v2.0에서는 사용 가능한 모든 Markdown 설정 옵션 (drafts를 제외한) 을 MDX 통합 설에서 개별적으로 설정할 수 있습니다.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      remarkPlugins: [remarkPlugin2],
      gfm: false,
    })
  ]
});

무엇을 해야 하나요?

마크다운 및 MDX 설정을 다시 살펴보고 기존 설정과 사용 가능한 새 옵션을 비교하세요.

변경됨: frontmatter에 대한 플러그인 접근 방식

v1.x에서는 remark 및 rehype 플러그인이 사용자 frontmatter에 액세스 할 수 없었습니다. Astro는 플러그인 frontmatter를 파일 frontmatter와 병합하여 파일 frontmatter를 플러그인에 전달하지 못했습니다.

Astro v2.0에서는 frontmatter injection을 통해 remark 및 rehype 플러그인이 사용자 frontmatter에 액세스 할 수 있게되었습니다. 이를 통해 플러그인 작성자는 사용자의 기존 frontmatter를 수정하거나 다른 속성을 기반으로 새 속성을 계산할 수 있습니다.

무엇을 해야 하나요?

작성한 모든 remark와 rehype 플러그인을 확인하여 동작이 변경되었는지 확인합니다. 이제 data.astro.frontmatter가 빈 객체가 아니라 마크다운 또는 MDX 문서의 완성된 프론트매터라는 점에 유의하세요.

변경됨: RSS 설정 변경

v1.x에서 Astro의 RSS 패키지는 items: import.meta.glob(...)를 사용하여 RSS 피드 목록을 생성할 수 있었습니다. 이 사용법은 이제 지원 중단되었으며, 추후 제거될 예정입니다.

Astro v2.0에는 items 속성에 pagesGlobToRssItems() 래퍼를 도입했습니다.

무엇을 해야 하나요?

pagesGlobToRssItems() 를 가져온 다음 import.meta.glob()를 포함하는 기존 함수를 pagesGlobToRssItems() 헬퍼로 래핑합니다.

import rss, {
  pagesGlobToRssItems
} from '@astrojs/rss';

export async function get(context) {
  return rss({
    items: await pagesGlobToRssItems(
      import.meta.glob('./blog/*.{md,mdx}'),
    ),
  });
}

변경됨: Svelte IDE 지원 변경

만약 @astrojs/svelteintegration 을 Astro v2.0과 함께 사용하려면 프로젝트에 svelte.config.js 파일이 필요합니다. 이 파일은 IDE 자동 완성 기능을 제공하는 데 필요합니다.

무엇을 해야 하나요?

프로젝트의 최상위 경로에 svelte.config.js 파일을 추가합니다.

import { vitePreprocess } from '@astrojs/svelte';

export default {
  preprocess: vitePreprocess(),
};

신규 사용자의 경우, 이 파일은 astro add svelte를 실행할 때 자동으로 추가됩니다.

삭제됨: `legacy.astroFlavoredMarkdown` 삭제

v1.0에서 Astro는 오래된 Astro-Flavored Markdown(마크다운의 구성 요소라고도 함)을 레거시 기능으로 옮겼습니다.

Astro v2.0에서는 legacy.astroFlavoredMarkdown 옵션이 완전히 제거되었습니다. .md 파일에서 컴포넌트를 가져와서 사용하는 것은 더 이상 작동하지 않습니다.

무엇을 해야 하나요?

이 레거시 옵션을 제거하세요. 이 옵션은 더 이상 Astro에서 사용할 수 없습니다.

export default defineConfig({
  legacy: {
    astroFlavoredMarkdown: true,
  },
})

만약 v1.x에서 이 기능을 사용 중이라면 컴포넌트와 JSX 표현식을 마크다운 구문과 결합할 수 있는 MDX 통합을 사용하는 것이 좋습니다.

삭제됨: `Astro.resolve()`

v0.24에서는 브라우저에서 참조할 수 있는 에셋에 대한 확인된 URL을 가져오기 위해 Astro.resolve()를 더 이상 사용하지 않았습니다.

Astro v2.0에서는 이 옵션이 완전히 제거되었습니다. 이제 코드에 Astro.resolve()를 사용하면 오류가 발생합니다.

무엇을 해야 하나요?

Astro.resolve()대신 import를 사용하여 에셋을 가져옵니다.

예:

---
import 'style.css';
import imageUrl from './image.png';
---

<img src={imageUrl} />

삭제됨: `Astro.fetchContent()`

v0.26에서 Astro는 로컬 마크다운 파일에서 데이터를 가져오기 위한 Astro.fetchContent()를 더 이상 지원하지 않습니다.

Astro v2.0에서는 이 옵션이 완전히 제거되었습니다. 코드에서 Astro.fetchContent()를 사용하면 오류가 발생합니다.

무엇을 해야 하나요?

마크다운 파일을 가져오기 위해 Astro.glob()을 사용하거나 Content Collections 기능으로 바꾸세요.

---
const allPosts = await Astro.glob('./posts/*.md');
---

삭제됨: `Astro.canonicalURL`

v1.0에서 Astro는 표준 URL을 구성하기 위해 Astro.canonicalURL을 더 이상 사용하지 않았습니다.

Astro v2.0에서는 이 옵션이 완전히 제거되었습니다. 코드에 Astro.canonicalURL이 있으면 오류가 발생합니다.

무엇을 해야 하나요?

Astro.url를 사용하여 캐노니컬 URL을 만들어보세요.

---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

업데이트: Vite 4

Astro v2.0는 Vite 3에서 2022년 10월에 출시된 Vite 4으로 업그레이드 했습니다.

무엇을 해야 하나요?

이번에는 코드에 변경할께 없습니다! Astro 내부에서 대부분의 업그레이드를 처리했지만, 일부 세부적인 Vite 동작은 버전 간에 변경점이 있을수있습니다.

문제가 생기면 공식 Vite 마이그레이션 가이드를 참조하세요

Astro v2.0 Experimental 지원 종료

astro.config.mjs 에서 experimental 항목을 제거하세요.

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    contentCollections: true,
    prerender: true,
    errorOverlay: true,
  },
})

다음 기능들이 이제 기본적으로 사용이 가능해졌습니다:

Content Collections을 사용하여 Markdown과 MDX 파일을 타입 안전하게 관리할 수 있습니다.
Prerendering individual pages to static HTML (EN)을 사용하여 속도와 캐시 가능성을 개선할 수 있습니다.
에러 메세지 오버레이의 디자인을 바꾸었습니다.

발견된 이슈

현재로선 발견된 이슈가 없습니다.

기여하기

커뮤니티

Astro v2로 업그레이드하기

Astro 업그레이드하기

Astro v2.0 중요한 변경 사항

Node.js 14에 대한 지원 종료

무엇을 해야 하나요?

변경됨: src/content/ 예약 폴더

무엇을 해야 하나요?

변경됨: Astro.site의 후행 슬래시

무엇을 해야 하나요?

변경됨: _astro/ 풀더 통합

무엇을 해야 하나요?

변경됨: 마크다운 플러그인 설정

extendDefaultPlugins 삭제됨

무엇을 해야 하나요?

신기능: gfm과 smartypants

무엇을 해야 하나요?

변경됨: MDX 플러그인 설정

extendPlugins 문법이 extendMarkdownConfig 로 변경되었습니다.

무엇을 해야 하나요?

Markdown과 일치하도록 더 많은 MDX 설정 옵션들이 추가되었습니다.

무엇을 해야 하나요?

변경됨: frontmatter에 대한 플러그인 접근 방식

무엇을 해야 하나요?

변경됨: RSS 설정 변경

무엇을 해야 하나요?

변경됨: Svelte IDE 지원 변경

무엇을 해야 하나요?

삭제됨: legacy.astroFlavoredMarkdown 삭제

무엇을 해야 하나요?

삭제됨: Astro.resolve()

무엇을 해야 하나요?

삭제됨: Astro.fetchContent()

무엇을 해야 하나요?

삭제됨: Astro.canonicalURL

무엇을 해야 하나요?

업데이트: Vite 4

무엇을 해야 하나요?

Astro v2.0 Experimental 지원 종료

발견된 이슈

변경됨: `src/content/` 예약 폴더

변경됨: `Astro.site`의 후행 슬래시

변경됨: `_astro/` 풀더 통합

`extendDefaultPlugins` 삭제됨

신기능: `gfm`과 `smartypants`

`extendPlugins` 문법이 `extendMarkdownConfig` 로 변경되었습니다.

삭제됨: `legacy.astroFlavoredMarkdown` 삭제

삭제됨: `Astro.resolve()`

삭제됨: `Astro.fetchContent()`

삭제됨: `Astro.canonicalURL`