콘텐츠로 이동

통합 작업

Astro 통합은 단 몇 줄의 코드만으로 프로젝트에 새로운 기능과 동작을 추가합니다. 공식 통합, 커뮤니티 통합 또는 심지어 사용자 정의 통합을 구축할 수도 있습니다.

통합은 다음을 수행할 수 있습니다.

  • 렌더러를 사용하여 React, Vue, Svelte, Solid 및 다른 인기 있는 UI 프레임워크를 잠금 해제합니다.
  • SSR 어댑터로 주문형 렌더링을 활성화합니다.
  • 몇 줄의 코드만으로 MDX 및 Partytown과 같은 도구를 추가합니다.
  • 자동 사이트맵 생성과 같은 새로운 기능을 프로젝트에 추가합니다.
  • 빌드 프로세스, 개발 서버 등에 연결되는 사용자 정의 코드를 작성합니다.

공식 통합

섹션 제목: “공식 통합”

다음 통합은 Astro에서 유지 관리합니다.

프런트엔드 프레임워크

어댑터

기타 통합

자동 통합 설정

섹션 제목: “자동 통합 설정”

Astro에는 공식 통합 설정을 자동화하는 astro add 명령이 포함되어 있습니다. 이 명령을 사용하여 여러 커뮤니티 플러그인을 추가할 수도 있습니다. astro add가 지원되는지 또는 수동으로 설치해야 하는지 확인하려면 각 통합의 문서를 확인하세요.

선택한 패키지 관리자를 사용하여 astro add 명령을 실행하면 자동 통합 마법사가 구성 파일을 업데이트하고 필요한 종속성을 설치합니다.

터미널 창
npx astro add react

동시에 여러 통합을 추가하는 것도 가능합니다!

터미널 창
npx astro add react sitemap partytown

수동 설치

섹션 제목: “수동 설치”

Astro 통합은 항상 astro.config.mjs 파일의 integrations 속성을 통해 추가됩니다.

Astro 프로젝트로 통합을 가져오는 세 가지 일반적인 방법이 있습니다.

  1. npm 패키지로 통합을 설치합니다.

  2. 프로젝트의 로컬 파일에서 자체 통합을 가져옵니다.

  3. 구성 파일에 직접 통합 인라인을 작성합니다.

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import installedIntegration from '@astrojs/vue';
    import localIntegration from './my-integration.js';
    

    export default defineConfig({
      integrations: [
        // 1. 설치된 npm 패키지에서 가져옵니다.
        installedIntegration(),
        // 2. 로컬 JS 파일에서 가져옵니다.
        localIntegration(),
        // 3. 인라인 객체를 작성합니다.
        {name: 'namespace:id', hooks: { /* ... */ }},
      ]
    });

통합을 작성할 수 있는 다양한 방법을 모두 알아보려면 통합 API 참조를 확인하세요.

npm 패키지 설치

섹션 제목: “npm 패키지 설치”

패키지 관리자를 사용하여 npm 패키지 통합을 설치한 다음 astro.config.mjs를 수동으로 업데이트하세요.

예를 들어 @astrojs/sitemap 통합을 설치하려면 다음을 수행하세요.

  1. 원하는 패키지 관리자를 사용하여 프로젝트 종속성에 대한 통합을 설치합니다.

    터미널 창
    npm install @astrojs/sitemap

  2. 통합을 astro.config.mjs 파일로 가져와 구성 옵션과 함께 integrations[] 배열에 추가합니다.

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import sitemap from '@astrojs/sitemap';
    

    export default defineConfig({
      // ...
      integrations: [sitemap()],
      // ...
    });

    통합마다 구성 설정이 다를 수 있습니다. 각 통합의 문서를 읽고 astro.config.mjs 파일에서 선택한 통합에 필요한 구성 옵션을 적용하세요.

맞춤 옵션

섹션 제목: “맞춤 옵션”

통합은 대부분의 경우 실제 통합 객체를 반환하는 팩토리 함수로 작성됩니다. 이를 통해 프로젝트 통합을 사용자 정의하는 팩토리 함수에 인수와 옵션을 전달할 수 있습니다.

integrations: [
  // 예: 함수 인수를 사용하여 통합 사용자 정의
  sitemap({filter: true})
]

통합 켜고 끄기

섹션 제목: “통합 켜고 끄기”

거짓 값을 나타내는 통합은 무시되므로 undefined 및 부울 값을 신경쓰지 않고 통합을 켜거나 끌 수 있습니다.

integrations: [
  // 예: Windows에서 사이트맵 작성 건너뛰기
  process.platform !== 'win32' && sitemap()
]

통합 업그레이드

섹션 제목: “통합 업그레이드”

모든 공식 통합을 한 번에 업그레이드하려면 @astrojs/upgrade 명령을 실행하세요. 그러면 Astro와 모든 공식 통합이 최신 버전으로 업그레이드됩니다.

자동 업그레이드

섹션 제목: “자동 업그레이드”
터미널 창
# Astro와 공식 통합을 최신 버전으로 함께 업그레이드
npx @astrojs/upgrade

수동 업그레이드

섹션 제목: “수동 업그레이드”

하나 이상의 통합을 수동으로 업그레이드하려면 패키지 관리자에 적합한 명령을 사용하세요.

터미널 창
# 예: React 및 Partytown 통합 업그레이드
npm install @astrojs/react@latest @astrojs/partytown@latest

통합 제거

섹션 제목: “통합 제거”

  1. 통합을 제거하려면 먼저 프로젝트에서 통합을 제거하세요.

    터미널 창
    npm uninstall @astrojs/react

  2. 그런 다음 astro.config.* 파일에서 통합을 제거합니다.

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    

    import react from '@astrojs/react';
    

    export default defineConfig({
      integrations: [
        react()
      ]
    });

더 많은 통합 찾기

섹션 제목: “더 많은 통합 찾기”

Astro 통합 디렉터리에서 커뮤니티에서 개발한 다양한 통합을 찾을 수 있습니다. 자세한 사용법 및 구성 지침을 보려면 해당 링크를 따르세요.

나만의 통합 구축

섹션 제목: “나만의 통합 구축”

Astro의 통합 API는 Rollup 및 Vite에서 영감을 얻었으며, 이전에 Rollup 또는 Vite 플러그인을 작성한 적이 있는 모든 사람에게 친숙하게 느껴지도록 설계되었습니다.

통합이 수행할 수 있는 작업과 직접 작성하는 방법을 알아보려면 통합 API 참조를 확인하세요.

npm에 통합 게시

섹션 제목: “npm에 통합 게시”

Astro 컴포넌트를 게시하는 것은 프로젝트 전반에 걸쳐 기존 작업을 재사용하고 더 넓은 Astro 커뮤니티와 공유할 수 있는 좋은 방법입니다. Astro 컴포넌트는 다른 JavaScript 패키지와 마찬가지로 npm에 직접 게시하고 설치할 수 있습니다.

영감을 찾고 계신가요? Astro 커뮤니티에서 우리가 가장 좋아하는 테마와 컴포넌트를 확인해 보세요. 전체 공개 카탈로그를 보기 위해 npm을 검색할 수도 있습니다.

빠른 시작

섹션 제목: “빠른 시작”

컴포넌트 개발을 빠르게 시작하기 위해 이미 설정된 템플릿을 사용할 수 있습니다.

터미널 창
# 새 디렉터리에서 Astro 컴포넌트 템플릿을 초기화합니다.
npm create astro@latest my-new-component-directory -- --template component
# yarn
yarn create astro my-new-component-directory --template component
# pnpm
pnpm create astro@latest my-new-component-directory -- --template component

패키지 생성

섹션 제목: “패키지 생성”

새 패키지를 만들려면 프로젝트에서 워크스페이스를 사용하도록 개발 환경을 구성하세요. 이를 통해 Astro의 작업 복사본과 함께 컴포넌트를 개발할 수 있습니다.

  • 디렉터리my-new-component-directory/
    • 디렉터리demo/
      • … 테스트 및 시연용
    • package.json
    • 디렉터리packages/
      • 디렉터리my-component/
        • index.js
        • package.json
        • … 패키지에서 사용되는 추가 파일

my-project라는 이 예시는 my-component라는 단일 패키지와 컴포넌트를 테스트하고 시연하기 위한 demo/ 디렉터리가 포함된 프로젝트를 만듭니다.

이는 프로젝트 루트의 package.json 파일에서 구성됩니다.

{
  "name": "my-project",
  "workspaces": ["demo", "packages/*"]
}

이 예시에서는 packages 디렉터리에서 여러 패키지를 함께 개발할 수 있습니다. 이 패키지는 Astro의 작업 복사본을 설치할 수 있는 demo에서 참조할 수도 있습니다.

터미널 창
npm create astro@latest demo -- --template minimal
# yarn
yarn create astro demo --template minimal
# pnpm
pnpm create astro@latest demo -- --template minimal

개별 패키지를 구성하는 두 개의 초기 파일은 package.json과 index.js입니다.

package.json

섹션 제목: “package.json”

패키지 디렉터리의 package.json 파일에는 설명, 종속성, 기타 패키지 메타데이터를 포함하여 패키지와 관련된 모든 정보가 포함되어 있습니다.

{
  "name": "my-component",
  "description": "Component description",
  "version": "1.0.0",
  "homepage": "https://github.com/owner/project#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  },
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"],
  "keywords": ["astro", "withastro", "astro-component", "...", "..."]
}
description
섹션 제목: “description”

다른 사람들이 해당 컴포넌트의 기능을 알 수 있도록 돕기 위해 사용되는 컴포넌트에 대한 간단한 설명입니다.

{
  "description": "An Astro Element Generator"
}
type
섹션 제목: “type”

Node.js와 Astro가 index.js 파일을 해석하기 위해 사용하는 모듈의 타입입니다.

{
  "type": "module"
}

index.js 파일을 import 및 export의 엔트리포인트로 사용할 수 있도록 "type": "module"을 사용하세요.

homepage
섹션 제목: “homepage”

프로젝트 홈페이지의 URL입니다.

{
  "homepage": "https://github.com/owner/project#readme"
}

이는 사용자를 프로젝트의 온라인 데모, 문서, 홈페이지로 안내하는 좋은 방법입니다.

exports
섹션 제목: “exports”

이름으로 가져올 때 패키지의 엔트리포인트입니다.

{
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  }
}

이 예시에서 my-component 가져오기는 index.js를 사용하고 my-component/astro 또는 my-component/react 가져오기는 각각 MyAstroComponent.astro 또는 MyReactComponent.jsx를 사용합니다.

files
섹션 제목: “files”

npm을 통해 사용자에게 제공되는 번들에서 불필요한 파일을 제외하는 선택적 최적화입니다. 여기에 나열된 파일만 패키지에 포함됩니다. 따라서 패키지가 작동하는 데 필요한 파일을 추가하거나 변경하는 경우 이 목록을 업데이트해야 합니다.

{
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"]
}
keywords
섹션 제목: “keywords”

다른 사람들이 npm 및 기타 검색 카탈로그에서 여러분의 컴포넌트를 찾는 데 도움이 되는 컴포넌트와 관련된 키워드 배열입니다.

Astro 생태계에서 검색 가능성을 극대화하려면 astro-component, astro-integration 또는 withastro를 특수 키워드로 추가하세요.

{
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

index.js

섹션 제목: “index.js”

패키지를 가져올 때마다 사용되는 기본 패키지 엔트리포인트입니다.

export { default as MyAstroComponent } from './MyAstroComponent.astro';


export { default as MyReactComponent } from './MyReactComponent.jsx';

이를 통해 여러 컴포넌트를 단일 인터페이스로 함께 패키징할 수 있습니다.

예: 명명된 가져오기 사용
섹션 제목: “예: 명명된 가져오기 사용”
---
import { MyAstroComponent } from 'my-component';
import { MyReactComponent } from 'my-component';
---
<MyAstroComponent />
<MyReactComponent />
예: 네임스페이스 가져오기 사용
섹션 제목: “예: 네임스페이스 가져오기 사용”
---
import * as Example from 'example-astro-component';
---
<Example.MyAstroComponent />
<Example.MyReactComponent />
예: 개별 가져오기 사용
섹션 제목: “예: 개별 가져오기 사용”
---
import MyAstroComponent from 'example-astro-component/astro';
import MyReactComponent from 'example-astro-component/react';
---
<MyAstroComponent />
<MyReactComponent />

패키지 개발

섹션 제목: “패키지 개발”

Astro에는 개발을 위한 전용 ‘패키지 모드’가 없습니다. 대신 데모 프로젝트를 사용하여 프로젝트에서 패키지를 개발하고 테스트해야 합니다. 이는 개발에만 사용되는 개인 웹사이트일 수도 있고 패키지에 대한 공개 데모/문서 웹사이트일 수도 있습니다.

기존 프로젝트에서 컴포넌트를 추출하는 경우 해당 프로젝트를 계속 사용하여 현재 추출된 컴포넌트를 개발할 수도 있습니다.

컴포넌트 테스트

섹션 제목: “컴포넌트 테스트”

Astro는 현재 테스트 러너를 출시하지 않았습니다. (이 문제에 관심이 있으시면 Discord에 참여하세요!)

그동안 테스트에 대한 현재 권장 사항은 다음과 같습니다.

  1. demo/src/pages 디렉터리에 테스트 fixtures 디렉터리를 추가하세요.

  2. 실행하려는 모든 테스트에 대해 새 페이지를 추가하세요.

  3. 각 페이지에는 테스트하려는 다양한 컴포넌트 사용법이 포함되어야 합니다.

  4. astro build 명령을 실행하여 fixtures를 빌드한 다음, dist/__fixtures__/ 디렉터리에 있는 결과물을 예상한 것과 비교하세요.

    • 디렉터리my-project/demo/src/pages/__fixtures__/
      • test-name-01.astro
      • test-name-02.astro
      • test-name-03.astro

컴포넌트 게시

섹션 제목: “컴포넌트 게시”

패키지가 준비되면 npm publish 명령을 사용하여 npm에 게시할 수 있습니다. 실패하면 npm login을 통해 로그인했는지, package.json 파일이 올바른지 확인하세요. 성공하면 끝입니다!

Astro 패키지에는 build 단계가 없다는 점에 유의하세요. .astro, .ts, .jsx, .css 등 Astro가 기본적으로 지원하는 모든 파일 형식은 빌드 단계 없이 직접 게시할 수 있습니다.

Astro에서 기본적으로 지원하지 않는 다른 파일 형식이 필요한 경우 패키지에 빌드 단계를 추가하세요. 이 고급 연습은 여러분에게 달려 있습니다.

통합 라이브러리

섹션 제목: “통합 라이브러리”

통합 라이브러리에 통합을 추가하여 여러분의 노력을 공유하세요!

package.json 데이터

섹션 제목: “package.json 데이터”

라이브러리는 매주 자동으로 업데이트되어 astro-component, astro-integration 또는 withastro 키워드를 사용하여 npm에 게시된 모든 패키지를 가져옵니다.

통합 라이브러리는 package.json 파일에서 name, description, repository, homepage 데이터를 읽습니다.

아바타는 라이브러리에서 브랜드를 강조할 수 있는 좋은 방법입니다! 패키지가 게시되면 아바타를 첨부하여 GitHub 이슈를 제출할 수 있으며 목록에 추가해 드리겠습니다.

카테고리

섹션 제목: “카테고리”

필수 키워드인 astro-component, astro-integration 또는 withastro 키워드 외에도 패키지를 자동으로 구성하는 데 특수 키워드도 사용됩니다. 아래 키워드 중 하나를 포함하면 통합 라이브러리의 일치하는 카테고리에 통합이 추가됩니다.

카테고리키워드
접근성a11y, accessibility
어댑터astro-adapter
분석analytics
CSS + UIcss, ui, icon, icons, renderer
프레임워크renderer
콘텐츠 로더astro-loader
이미지 + 미디어media, image, images, video, audio
성능 + SEOperformance, perf, seo, optimization
개발 툴바devtools, dev-overlay, dev-toolbar
유틸리티tooling, utils, utility

카테고리와 일치하는 키워드를 포함하지 않는 패키지는 Uncategorized으로 표시됩니다.

공유

섹션 제목: “공유”

우리는 여러분의 작업을 공유하도록 권장하며, 우리의 재능 있는 Astronauts가 창조하는 것을 보는 것을 정말 좋아합니다. 오셔서 여러분이 만든 것을 Discord에서 공유하거나 트윗에서 @astrodotbuild를 멘션해 주세요!

기여하기 커뮤니티 후원하기