npm에 게시

새로운 Astro 컴포넌트를 구축하시나요? 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 파일에는 설명, 종속성, 기타 패키지 메타데이터를 포함하여 패키지와 관련된 모든 정보가 포함되어 있습니다.

{
  "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": "An Astro Element Generator"
}

`type`

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

{
  "type": "module"
}

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

`homepage`

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

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

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

`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`

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

{
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"]
}

`keywords`

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

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

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

`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에 참여하세요!)

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

demo/src/pages 디렉터리에 테스트 fixtures 디렉터리를 추가하세요.
실행하려는 모든 테스트에 대해 새 페이지를 추가하세요.
각 페이지에는 테스트하려는 다양한 컴포넌트 사용법이 포함되어야 합니다.
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` 데이터

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

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

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

카테고리

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

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

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

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

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