发布到 NPM

正在构建一个新的 Astro 组件？把它发布到 npm 吧！

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

在寻找灵感吗？可以看看我们最喜欢的来自 Astro 社区的主题和组件。你也可以在 npm 上搜索来查看整个公共目录。

不想单打独斗？

查看 Astro 社区的组件模板，这是一个由社区支持的、开箱即用的模板！

快速开始

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

# 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

创建一个包

先决条件

在深入之前，对以下内容有基本的了解会很有帮助：

• Node 模块
• 包清单（package.json）
• 工作区

要创建一个新包，请配置你的开发环境以在项目中使用工作区。这将允许你在一个可运行的 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 目录中一起开发多个包。这些包也可以从 demo 中引用，你可以在其中安装一个可运行的 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。

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

类型

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

{
  "type": "module"
}

使用 "type": "module"，这样你的 index.js 就可以作为入口点，并使用 import 和 export。

主页

项目主页的 URL。

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

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

导出

通过名称导入包时的入口点。

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

在这个例子中，导入 my-component 会使用 index.js，而导入 my-component/astro 或 my-component/react 会分别使用 MyAstroComponent.astro 或 MyReactComponent.jsx。

文件

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

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

关键字

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

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

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

提示

我们的集成库也会使用关键字！请见下文，查看我们在 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 目录。

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 原生支持的文件类型，如 .astro、.ts、.jsx 和 .css，都可以直接发布而无需构建步骤。

如果你需要 Astro 不原生支持的其他文件类型，请为你的包添加一个构建步骤。这个高级练习留给你自己完成。

集成库

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

提示

在构建集成时需要帮助，或者只是想认识其他集成构建者吗？我们在 Discord 服务器上有一个专门的 #integrations 频道。快来打个招呼吧！

package.json 数据

该库每周自动更新，拉取所有发布到 NPM 上且带有 astro-component 或 withastro 关键字的包。

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

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

提示

需要覆盖我们的库从 NPM 读取的信息吗？没问题！提交一个 issue 并附上更新后的信息，我们会确保使用自定义的 name、description 或 homepage。

分类

除了必需的 astro-component 或 withastro 关键字外，特殊的关键字也用于自动组织包。包含以下任何关键字都会将你的集成添加到我们集成库中相应的分类。

分类	关键字
无障碍性	a11y, accessibility
适配器	Astro 适配器
分析	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（未分类）。

分享

我们鼓励你分享你的工作，我们真心喜欢看到我们才华横溢的宇航员们创造的作品。来我们的 Discord 中分享你的创作，或者在推文中提及 @astrodotbuild！