跳转到内容

发布到 NPM

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

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

正在寻找灵感?不妨看看一些受人喜欢的主题组件。你也可以在 npm 中搜索查看所有公开分类。

快速开始

你可以使用已经配置好的模板快速开始开发你的组件。

Terminal window
# 在新目录下初始化 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 目录中引用这些模块。

Terminal window
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.jsonindex.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","astro-component", "...", "..."]
}

description

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

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

type

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

{
"type": "module"
}

使用 "type": "module" 以便你的 index.js 可以用作 importexport 的入口。

homepage

项目主页链接。

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

它可以很好地将用户引向项目的在线示例、文档或是主页。

exports

当使用模块名称导入时的入口文件。

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

在这个示例中,导入 my-component 会使用 index.js。而当导入 my-component/astromy-component/react 则会分别使用 MyAstroComponent.astroMyReactComponent.jsx

files

一个可选的优化项,它可以在通过分发给 npm 运给用户的模块中排除不必要的文件。请注意,只有在此列出的文件才会打包到在你的模块中,所以如果你增加或改变了模块运行所需的文件,你必须相应地更新这个列表。

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

keywords

一些与组件相关的关键词,用来帮助别人在 npm 上和任何其他检索目录上找到你的组件。

添加特殊关键词 astro-componentwithastro,以最大限度地提高它在 Astro 生态系统中的可发现性。

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

同时,我们目前对测试的建议有:

  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 publish 命令将其发布到 npm。如果发布失败,请确保你已经使用 npm login 登录了 npm 账号,并 package.json 文件没有问题。如果发布成功,那就好了!

注意 Astro 模块没有 build 步骤。Astro 本身支持的任何类型文件(例如 .astro.ts.jsx.css)都可以直接发布,无需构建步骤。

如果你需要使用 Astro 本身不支持的文件类型,请在模块中增加一个构建步骤。

集成库

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

package.json 数据

该库每周自动更新,拉入每一个使用 astro-component 或者 withastro 关键字发布到 NPM 的模块。

它会从模块的 package.json 文件中读取 namedescriptionrepositoryhomepage 数据。

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

集合

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

集合关键词
无障碍辅助功能a11y, accessibility
适配器astro-adapter
统计analytics
CSS + UIcss, ui, icon, icons, renderer
框架renderer
性能 + SEOperformance, perf, seo, optimization

分享

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