Publish to NPM
Building a new Astro component? Publish it to npm!
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.
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.
Quick Start
Section titled Quick StartTo get started developing your component quickly, we have a template already setup 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
Creating a package
Section titled Creating a packageTo create a new package we strongly recommend configuring your development environment to use workspaces within your project. This will allow you to develop your component alongside a working copy of Astro.
my-new-component-directory/
demo/
- … for testing and demonstration
- package.json
packages/
my-component/
- index.js
- package.json
- … additional files used by the package
In this example, named my-project
, we create a project with a single package, named my-component
, and a demo/
directory for testing and demonstrating the component.
This is configured in the project root’s package.json
file.
{
"name": "my-project",
"workspaces": ["demo", "packages/*"]
}
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
There are two initial files that will make up your individual package: package.json
and index.js
.
package.json
Section titled package.jsonThe 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 descriptionA short description of your component used to help others know what it does.
{
"description": "An Astro Element Generator"
}
The module format used by Node.js and Astro to interpret your index.js
files.
{
"type": "module"
}
We recommend using "type": "module"
so that your index.js
can be used as an entrypoint with import
and export
.
package.json#homepage
Section titled package.json#homepageThe 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.
package.json#exports
Section titled package.json#exportsThe entry points of a package when imported by name.
{
"exports": {
".": "./index.js",
"./astro": "./MyAstroComponent.astro",
"./react": "./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 filesThis is 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 keywordsAn array of keywords relevant to your component that are used to help others find your component on npm and in any other search catalogs.
We recommend adding astro-component
or withastro
as a special keyword to maximize its discoverability in the Astro ecosystem.
{
"keywords": ["astro-component", "withastro", "... etc", "... etc"]
}
index.js
Section titled index.jsThe 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.
Example: Using Named Imports
Section titled Example: Using Named Imports---
import { MyAstroComponent } from 'my-component';
import { MyReactComponent } from 'my-component';
---
<MyAstroComponent />
<MyReactComponent />
Example: Using Namespace Imports
Section titled Example: Using Namespace Imports---
import * as Example from 'example-astro-component';
---
<Example.MyAstroComponent />
<Example.MyReactComponent />
Example: Using Individual Imports
Section titled Example: Using Individual Imports---
import MyAstroComponent from 'example-astro-component/astro';
import MyReactComponent from 'example-astro-component/react';
---
<MyAstroComponent />
<MyReactComponent />
Developing your package
Section titled Developing your packageAstro 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.
Testing your component
Section titled Testing your componentAstro does not currently ship a test runner. This is something that we would like to tackle. (If you are interested in helping out, join us on Discord!)
In the meantime, our current recommendation for testing is:
- Add a test
fixtures
directory to yourdemo/src/pages
directory. - Add a new page for every test that you’d like to run.
- Each page should include some different component usage that you’d like to test.
- Run
astro build
to build your fixtures, then compare the output of thedist/__fixtures__/
directory to what you expected.
my-project/demo/src/pages/__fixtures__/
- test-name-01.astro
- test-name-02.astro
- test-name-03.astro
Publishing your component
Section titled Publishing your componentOnce you have your package ready, you can publish it to npm!
To publish a package to npm, use 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!
Notice that there was no build
step for Astro packages. Any file type that Astro supports can be published directly without a build step, because we know that Astro already supports them natively. This includes all files with extensions like .astro
, .ts
, .jsx
, and .css
.
If you need some other file type that isn’t natively supported by Astro, you are welcome to add a build step to your package. This advanced exercise is left up to you.
Integrations Library
Section titled Integrations LibraryShare your hard work by adding your integration to our integrations library!
package.json
data
Section titled package.json dataThe library is automatically updated nightly, pulling in every package published to NPM with the astro-component
or withastro
keyword.
The integrations library reads the name
, description
, repository
, and homepage
data from your package.json
.
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.
Collections
Section titled CollectionsIn 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 collection in our integrations library.
collection | keywords |
---|---|
Accessibility | a11y , accessibility |
Adapters | astro-adapter |
Analytics | analytics |
CSS + UI | css , ui , icon , icons , renderer |
Frameworks | renderer |
Performance + SEO | performance , perf , seo , optimization |
Share
Section titled ShareWe 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!