Building a new Astro component? Publish it to npm!
Quick StartSection titled Quick Start
To get started developing your component quickly, we have a template already setup for you.
Creating a packageSection titled Creating a package
To create a new package we strongly recommend configuring your development enviroment to use workspaces within your project. This will allow you to develop your component alongside a working copy of Astro.
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
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.
There are two initial files that will make up your individual package:
Section titled package.json
package.json in the package directory includes all of the information related to your package, including its description, dependencies, and any other package metadata.
Section titled description
A short description of your component used to help others know what it does.
The module format used by Node.js and Astro to interpret your
We recommend using
"type": "module" so that your
index.js can be used as an entrypoint with
Section titled package.json#homepage
The url to the project homepage.
This is a great way to direct users to an online demo, documentation, or homepage for your project.
Section titled package.json#exports
The entry points of a package when imported by name.
In this example, importing
my-component would use
index.js, while importing
my-component/react would use
Section titled files
This 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.
Section titled keywords
An 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
withastro as a special keyword to maximize its discoverability in the Astro ecosystem.
Section titled index.js
The main package entrypoint used whenever your package is imported.
This allows you to package multiple components together into a single interface.
Example: Using Named ImportsSection titled Example: Using Named Imports
Example: Using Namespace ImportsSection titled Example: Using Namespace Imports
Example: Using Individual ImportsSection titled Example: Using Individual Imports
Developing your packageSection titled Developing your package
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.
Testing your componentSection titled Testing your component
Astro 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
fixturesdirectory to your
- 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.
astro buildto build your fixtures, then compare the output of the
dist/__fixtures__/directory to what you expected.
Publishing your componentSection titled Publishing your component
Once 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
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 LibrarySection titled Integrations Library
Share your hard work by adding your integration to our integrations library!
Section titled package.json data
The library is automatically updated nightly, pulling in every package published to NPM with the
The integrations library reads the
homepage data from your
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.
CollectionsSection titled Collections
In addition to the required
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.
|CSS + UI||
|Performance + SEO||