发布到 NPM

构建新的 Astro 组件？发布到 嗯！

¥Building a new Astro component? Publish it to npm!

发布 Astro 组件是在项目中重用现有工作并与更广泛的 Astro 社区共享的好方法。Astro 组件可以直接发布到 NPM 并从 NPM 安装，就像任何其他 JavaScript 包一样。

¥Publishing an Astro component is a great way to reuse your existing work across your projects, and to share with the wider Astro community at large. Astro components can be published directly to and installed from NPM, just like any other JavaScript package.

寻找灵感？查看 Astro 社区中我们最喜欢的一些 themes 和 components。你还可以 搜索 npm 查看整个公共目录。

¥Looking for inspiration? Check out some of our favorite themes and components from the Astro community. You can also search npm to see the entire public catalog.

Don’t want to go it alone?

Check out Astro Community’s component template for a community-supported, out-of-the-box template!

快速开始

Section titled 快速开始

¥Quick Start

要快速开始开发组件，你可以使用已为你设置的模板。

¥To get started developing your component quickly, you can use a template already set up for you.

# Initialize the Astro Component template in a new directory
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

创建包

Section titled 创建包

¥Creating a package

Prerequisites

Before diving in, it will help to have a basic understanding of:

• Node Modules
• Package Manifest (package.json)
• Workspaces

要创建新包，请配置开发环境以使用项目中的工作区。这将允许你与 Astro 的工作副本一起开发你的组件。

¥To create a new package, configure your development environment to use workspaces within your project. This will allow you to develop your component alongside a working copy of Astro.

• Directorymy-new-component-directory/

  • Directorydemo/

    • … for testing and demonstration
  • package.json
  • Directorypackages/

    • Directorymy-component/

      • index.js
      • package.json
      • … additional files used by the package

此示例（名为 my-project）创建一个项目，其中包含一个名为 my-component 的包，以及一个用于测试和演示该组件的 demo/ 目录。

¥This example, named my-project, creates a project with a single package, named my-component, and a demo/ directory for testing and demonstrating the component.

这是在项目根目录的 package.json 文件中配置的：

¥This is configured in the project root’s package.json file:

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

在本例中，可以从 packages 目录一起开发多个包。这些软件包也可以从 demo 引用，你可以在其中安装 Astro 的工作副本。

¥In this example, multiple packages can be developed together from the packages directory. These packages can also be referenced from demo, where you can install a working copy of Astro.

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。

¥There are two initial files that will make up your individual package: package.json and index.js.

package.json

Section titled package.json

包目录中的 package.json 包含与包相关的所有信息，包括其描述、依赖和任何其他包元数据。

¥The package.json in the package directory includes all of the information related to your package, including its description, dependencies, and any other package metadata.

{
  "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

Section titled description

组件的简短描述，用于帮助其他人了解它的用途。

¥A short description of your component used to help others know what it does.

{
  "description": "An Astro Element Generator"
}

type

Section titled type

Node.js 和 Astro 用来解释 index.js 文件的模块格式。

¥The module format used by Node.js and Astro to interpret your index.js files.

{
  "type": "module"
}

使用 "type": "module" 以便你的 index.js 可以用作 import 和 export 的入口点。

¥Use "type": "module" so that your index.js can be used as an entrypoint with import and export .

homepage

Section titled homepage

项目主页的 url。

¥The url to the project homepage.

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

这是引导用户访问项目的在线演示、文档或主页的好方法。

¥This is a great way to direct users to an online demo, documentation, or homepage for your project.

exports

Section titled exports

按名称导入时包的入口点。

¥The entry points of a package when imported by name.

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

在此示例中，导入 my-component 将使用 index.js，而导入 my-component/astro 或 my-component/react 将分别使用 MyAstroComponent.astro 或 MyReactComponent.jsx。

¥In this example, importing my-component would use index.js, while importing my-component/astro or my-component/react would use MyAstroComponent.astro or MyReactComponent.jsx respectively.

files

Section titled files

一项可选的优化，用于从通过 npm 发送给用户的打包包中排除不必要的文件。请注意，只有此处列出的文件才会包含在你的包中，因此如果你添加或更改包运行所需的文件，则必须相应地更新此列表。

¥An optional optimization to exclude unnecessary files from the bundle shipped to users via npm. Note that only files listed here will be included in your package, so if you add or change files necessary for your package to work, you must update this list accordingly.

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

keywords

Section titled keywords

与你的组件相关的一组关键字，用于帮助其他人 在 npm 上找到你的组件 以及任何其他搜索目录。

¥An array of keywords relevant to your component, used to help others find your component on npm and in any other search catalogs.

添加 astro-component 或 withastro 作为特殊关键字，以最大限度地提高其在 Astro 生态系统中的可发现性。

¥Add astro-component or withastro as a special keyword to maximize its discoverability in the Astro ecosystem.

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

Tip

Keywords are also used by our integrations library! See below for a full list of keywords we look for in NPM.

---

index.js

Section titled index.js

每当导入你的包时使用的主要包入口点。

¥The main package entrypoint used whenever your package is imported.

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

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

这允许你将多个组件打包到一个接口中。

¥This allows you to package multiple components together into a single interface.

示例：使用命名导入

Section titled 示例：使用命名导入

¥Example: Using Named Imports

---
import { MyAstroComponent } from 'my-component';
import { MyReactComponent } from 'my-component';
---
<MyAstroComponent />
<MyReactComponent />

示例：使用命名空间导入

Section titled 示例：使用命名空间导入

¥Example: Using Namespace Imports

---
import * as Example from 'example-astro-component';
---
<Example.MyAstroComponent />
<Example.MyReactComponent />

示例：使用单独导入

Section titled 示例：使用单独导入

¥Example: Using Individual Imports

---
import MyAstroComponent from 'example-astro-component/astro';
import MyReactComponent from 'example-astro-component/react';
---
<MyAstroComponent />
<MyReactComponent />

---

开发你的包

Section titled 开发你的包

¥Developing your package

Astro 没有专门用于开发的 “封装模式”。相反，你应该使用演示项目在项目内开发和测试你的包。这可以是仅用于开发的私有网站，也可以是你的包的公共演示/文档网站。

¥Astro does not have a dedicated “package mode” for development. Instead, you should use a demo project to develop and test your package inside of your project. This can be a private website only used for development, or a public demo/documentation website for your package.

如果你从现有项目中提取组件，你甚至可以继续使用该项目来开发现在提取的组件。

¥If you are extracting components from an existing project, you can even continue to use that project to develop your now-extracted components.

测试你的组件

Section titled 测试你的组件

¥Testing your component

Astro 目前不提供测试运行程序。（如果你有兴趣帮忙解决这个问题，加入我们的 Discord！）

¥Astro does not currently ship a test runner. (If you are interested in helping out with this, join us on Discord!)

同时，我们当前的测试建议是：

¥In the meantime, our current recommendation for testing is:

1. Add a test fixtures directory to your demo/src/pages directory.

2. Add a new page for every test that you’d like to run.

3. Each page should include some different component usage that you’d like to test.

4. Run astro build to build your fixtures, then compare the output of the dist/__fixtures__/ directory to what you expected.

   • Directorymy-project/demo/src/pages/__fixtures__/

     • test-name-01.astro
     • test-name-02.astro
     • test-name-03.astro

发布你的组件

Section titled 发布你的组件

¥Publishing your component

准备好包后，你可以使用 npm publish 命令将其发布到 npm。如果失败，请确保你已通过 npm login 登录并且你的 package.json 正确。如果成功了，你就完成了！

¥Once you have your package ready, you can publish it to npm using the npm publish command. If that fails, make sure that you have logged in via npm login and that your package.json is correct. If it succeeds, you’re done!

请注意，Astro 软件包没有 build 步骤。Astro 本身支持的任何文件类型（例如 .astro、.ts、.jsx 和 .css）都可以直接发布，无需构建步骤。

¥Notice that there was no build step for Astro packages. Any file type that Astro supports natively, such as .astro, .ts, .jsx, and .css, can be published directly without a build step.

如果你需要 Astro 本身不支持的其他文件类型，请向你的包中添加构建步骤。这项高级练习由你决定。

¥If you need another file type that isn’t natively supported by Astro, add a build step to your package. This advanced exercise is left up to you.

集成库

Section titled 集成库

¥Integrations Library

通过将你的集成添加到我们的 集成库 来分享你的辛勤工作！

¥Share your hard work by adding your integration to our integrations library!

Tip

Do you need some help building your integration, or just want to meet other integrations builders? We have a dedicated #integrations channel on our Discord server. Come say hi!

package.json 数据

Section titled package.json 数据

¥package.json data

该库每周自动更新，使用 astro-component 或 withastro 关键字提取发布到 NPM 的每个包。

¥The library is automatically updated weekly, pulling in every package published to NPM with the astro-component or withastro keyword.

集成库从 package.json 读取 name、description、repository 和 homepage 数据。

¥The integrations library reads the name, description, repository, and homepage data from your package.json.

头像是在库中突出你的品牌的好方法！一旦你的包发布，你可以 提交 GitHub 问题 附上你的头像，我们会将其添加到你的列表中。

¥Avatars are a great way to highlight your brand in the library! Once your package is published you can file a GitHub issue with your avatar attached and we will add it to your listing.

Tip

Need to override the information our library reads from NPM? No problem! File an issue with the updated information and we’ll make sure the custom name, description, or homepage is used instead.

类别

Section titled 类别

¥Categories

除了必需的 astro-component 或 withastro 关键字外，还使用特殊关键字来自动组织包。包括以下任何关键字都会将你的集成添加到我们集成库中的匹配类别中。

¥In addition to the required astro-component or withastro keyword, special keywords are also used to automatically organize packages. Including any of the keywords below will add your integration to the matching category in our integrations library.

category	keywords
无障碍	a11y、accessibility
适配器	astro-adapter
分析	analytics
CSS+用户界面	css、ui、icon、icons、renderer
构架	renderer
内容加载器	astro-loader
图片 + 媒体	media、image、images、video、audio
性能+搜索引擎优化	performance、perf、seo、optimization
开发工具栏	devtools, dev-overlay, dev-toolbar
实用程序	tooling, utils, utility

不包含任何与类别匹配的关键字的包将显示为 Uncategorized。

¥Packages that don’t include any keyword matching a category will be shown as Uncategorized.

分享

Section titled 分享

¥Share

我们鼓励你分享你的工作，我们真的很喜欢看到我们才华横溢的宇航员创造的东西。快来在 Discord 中与我们分享你的创作成果，或在推文中提及 @astrodotbuild！

¥We encourage you to share your work, and we really do love seeing what our talented Astronauts create. Come and share what you create with us in our Discord or mention @astrodotbuild in a Tweet!