Skip to content

Latest commit

 

History

History
295 lines (211 loc) · 11.7 KB

publish-to-npm.mdx

File metadata and controls

295 lines (211 loc) · 11.7 KB
Raw
title description i18nReady
NPM에 게시
Astro 컴포넌트를 NPM에 게시하는 방법 알아보기
true

import { Steps } from '@astrojs/starlight/components'; import { FileTree } from '@astrojs/starlight/components';

새로운 Astro 컴포넌트를 구축하시나요? npm에 게시하세요!

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

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

:::tip[혼자 시작하고 싶지 않으신가요?] 커뮤니티에서 지원하는 기본 템플릿을 보려면 Astro 커뮤니티의 컴포넌트 템플릿을 확인하세요! :::

빠른 시작

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

# 새 디렉터리에서 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

패키지 생성

:::note[전제조건] 시작하기 전에 다음 사항에 대한 기본적인 이해를 갖추는 것이 도움이 됩니다.

새 패키지를 만들려면 프로젝트에서 워크스페이스을 사용하도록 개발 환경을 구성하세요. 이를 통해 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 또는 withastro를 특수 키워드로 추가하세요.

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

:::tip 키워드는 통합 라이브러리에서도 사용됩니다! NPM에서 찾는 키워드의 전체 목록은 아래를 참조하세요. :::

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` 디렉터리를 추가하세요.

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

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

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

통합 라이브러리

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

:::tip 통합을 구축하는 데 도움이 필요하거나 다른 통합 빌더가 필요하신가요? Discord 서버에는 전용 #integrations 채널이 있습니다. 방문하여 인사를 나누세요! :::

package.json 데이터

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

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

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

:::tip 우리의 라이브러리가 NPM에서 읽는 정보를 재정의해야 합니까? 괜찮아요! 업데이트된 정보로 issue를 제출해 주시면 맞춤 name, description, homepage가 대신 사용되도록 하겠습니다. :::

컬렉션

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

컬렉션 키워드
접근성 a11y, accessibility
어댑터 astro-adapter
분석 analytics
CSS + UI css, ui, icon, icons, renderer
프레임워크 renderer
성능 + SEO performance, perf, seo, optimization

공유

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