发布到 NPM

创建了一个新的 Astro 组件？发布到 npm！

发布 Astro 组件是个很好跨项目复用现有内容，并最大程度与 Astro 社群分享的方式。Astro 组件可以直接发布到 NPM 以及从中安装，和其他 JavaScript 包一样。

正在寻找灵感？不妨看看一些受人喜欢的主题和组件。你也可以在 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 my-new-component-directory --template minimal
# pnpm
pnpm create astro@latest my-new-component-directory -- --template minimal

这两个初始文件构成了你的个人模块：package.json 和 index.js。

模块目录下的 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","astro-component", "...", "..."]
}

一个帮助其他人了解模块用途的简要描述。

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

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

{
  "type": "module"
}

我们推荐使用 "type": "module" 这样 import 和 export 可以将 index.js 视作入口。

项目主页链接。

{
  "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，以最大限度地提高它在 Astro 生态系统中的可发现性。

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

每当你使用包时的主要入门函数

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 进行构建，然后比较 dist/__fixtures__/ 目录的输出与预期间的差异。

my-project/demo/src/pages/__fixtures__/
  ├─ test-name-01.astro
  ├─ test-name-02.astro
  └─ test-name-03.astro

当模块准备就绪就可以发布到 npm 上了！

使用 npm publish 命令将模块发布到 npm。如果发布失败，请确保你已经使用 npm login 登录了 npm 账号 ，并 package.json 文件没有问题。如果发布成功，那就好了！

注意 Astro 模块没有 build 步骤。无需构建即可直接发布受 Astro 支持的任何类型文件，因为 Astro 已经原生支持它们了。支持的文件类型有 .astro、.ts、.jsx 和 .css。

如果你需要使用不受 Astro 支持的文件类型，你可以在模块中增加一个构建步骤。

欢迎通过集成库分享你的辛勤工作。

该库每晚自动更新，拉入每一个使用 astro-component 关键字发布到 NPM 的模块。

它会从模块的 package.json 文件中读取 name、description、repository 和 homepage 数据。

添加头像是凸显品牌的好方法。在你的的模块发布后，你可以在 GitHub 提交一个 issue并附上你的头像，我们会把它添加到列表中。

除了必要的 astro-component 关键词外，我们也会使用特殊的关键词将模块进行分类。包括以下任一关键词都会将你的集成添加到相应的集合中。

我们鼓励你分享创造，我们真的很喜欢看到有才华的 Astronauts 创作。来吧，在我们的 Discord 服务器中与我们分享你的创作，或者在 Twitter 中提及@astrodotbuild!