Infrastructure/astro
0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2024-12-23 21:53:55 -05:00
Code Issues Activity

[ci] yarn format

Browse source
This commit is contained in:
FredKSchott 2021-09-07 18:41:08 +00:00 committed by GitHub Actions
parent bf4ba7c3ee
commit 105be57f80
1 changed files with 23 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
docs/src/pages/guides/publish-to-npm.md
View file

@ -3,7 +3,7 @@ layout: ~/layouts/MainLayout.astro
title: Publish to NPM
---
Building a new Astro component? **Publish it to [npm!][NPM]**
Building a new Astro component? **Publish it to [npm!][npm]**
Publishing a component is a great way to reuse work across your team, your company, or the entire world. Astro components can be published to and installed from npm, just like any other JavaScript package.
@ -13,8 +13,9 @@ Even if you don't plan on publishing your components online, the patterns outlin
> **Note - Experimental:** Published npm components are still marked as experimental and some features are not yet supported. Astro component styles are currently disabled inside of npm packages, and JSX components must be compiled to `.js` in the package.
## Featured packages
Looking for inspiration? Check out some of [our favorite themes & components][Themes] from the Astro community. You can also [search npm][Published-Astro-Components] to see the entire public catalog.
## Featured packages
Looking for inspiration? Check out some of [our favorite themes & components][themes] from the Astro community. You can also [search npm][published-astro-components] to see the entire public catalog.
## Folder layout
@ -37,11 +38,11 @@ Lets explore the different files that will make up your package:
### `package.json`
Your package `package.json` file is known as your **package manifest.** Every package published to npm has one. This includes important configuration such as name, description, dependencies, and other package metadata. To publish anything to npm, it helps to have [a basic understanding][Creating-A-Package.json] of this JSON manifest format.
Your package `package.json` file is known as your **package manifest.** Every package published to npm has one. This includes important configuration such as name, description, dependencies, and other package metadata. To publish anything to npm, it helps to have [a basic understanding][creating-a-package.json] of this JSON manifest format.
#### Recommended: "keywords"
When publishing an Astro component, include the `astro-component` keyword in your package.json file. This makes it easier for people to [find your component on npm][Published-Astro-Components] and other search catalogs.
When publishing an Astro component, include the `astro-component` keyword in your package.json file. This makes it easier for people to [find your component on npm][published-astro-components] and other search catalogs.
```json
{
@ -51,7 +52,7 @@ When publishing an Astro component, include the `astro-component` keyword in you
#### Recommended: "exports"
We **strongly recommend** that you include an [exports entry][Node-Packages-API] in your `package.json`. This entry controls access to internal package files, and gives you more control over how users can import your package.
We **strongly recommend** that you include an [exports entry][node-packages-api] in your `package.json`. This entry controls access to internal package files, and gives you more control over how users can import your package.
```json
{
@ -78,7 +79,7 @@ We **strongly recommend** that you use an `index.js` package entrypoint to avoid
```js
// ✅ Do this:
import {Bold, Capitalize} from 'package-name';
import { Bold, Capitalize } from 'package-name';
// ❌ Avoid this:
import Bold from 'package-name/Bold.astro';
@ -107,17 +108,17 @@ Astro does not have a dedicated "package mode" for development. Instead, you sh
If you are extracting components from an existing project, you can even continue to use that project to develop your now-extracted components.
For development, we **strongly recommend** that you setup a [**project workspace.**][Node-Packages-Workspace] Workspaces are a feature supported by all package managers including npm (v7+), yarn, pnpm and others. A workspace will help you verify package.json configuration and also let you import your package by name:
For development, we **strongly recommend** that you setup a [**project workspace.**][node-packages-workspace] Workspaces are a feature supported by all package managers including npm (v7+), yarn, pnpm and others. A workspace will help you verify package.json configuration and also let you import your package by name:
```js
// ✅ With workspaces:
import {Bold, Capitalize} from 'package-name';
import { Bold, Capitalize } from 'package-name';
// ❌ Without workspaces:
import {Bold, Capitalize} from '../../../my-package-directory/index.js';
import { Bold, Capitalize } from '../../../my-package-directory/index.js';
```
To turn your project into a workspace, create a `package.json` file at the top-most level of your repository (if one doesn't already exist) and add a `"workspaces"` entry that identifies your `packages/` directory as a collection of packages:
To turn your project into a workspace, create a `package.json` file at the top-most level of your repository (if one doesn't already exist) and add a `"workspaces"` entry that identifies your `packages/` directory as a collection of packages:
```diff
{
@ -144,7 +145,7 @@ You can optionally choose to move your development website's `src/` and `public/
## Testing your component
Astro does not currently ship a test runner. This is something that we would like to tackle before our v1.0 release. *(If you are interested in helping out, [join us on Discord!][Astro-Discord])*
Astro does not currently ship a test runner. This is something that we would like to tackle before our v1.0 release. _(If you are interested in helping out, [join us on Discord!][astro-discord])_
In the meantime, our current recommendation for testing is:
@ -170,13 +171,13 @@ Notice that there was no `build` step for Astro packages. Any file type that Ast
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.
[Themes]: /themes
[NPM]: https://npmjs.com/
[Accessible-Astro-Components]: https://www.npmjs.com/package/accessible-astro-components
[Astro-Static-Tweet]: https://www.npmjs.com/package/@rebelchris/astro-static-tweet
[Astro-SEO]: https://github.com/jonasmerlin/astro-seo
[Published-Astro-Components]: https://www.npmjs.com/search?q=keywords%3Aastro-component
[Creating-A-Package.json]: https://docs.npmjs.com/creating-a-package-json-file
[Node-Packages-API]: https://nodejs.org/api/packages.html
[Node-Packages-Workspace]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#workspaces
[Astro-Discord]: https://astro.build/chat
[themes]: /themes
[npm]: https://npmjs.com/
[accessible-astro-components]: https://www.npmjs.com/package/accessible-astro-components
[astro-static-tweet]: https://www.npmjs.com/package/@rebelchris/astro-static-tweet
[astro-seo]: https://github.com/jonasmerlin/astro-seo
[published-astro-components]: https://www.npmjs.com/search?q=keywords%3Aastro-component
[creating-a-package.json]: https://docs.npmjs.com/creating-a-package-json-file
[node-packages-api]: https://nodejs.org/api/packages.html
[node-packages-workspace]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#workspaces
[astro-discord]: https://astro.build/chat