|
| 1 | +# Astro Component Template 🧑🚀 |
| 2 | + |
| 3 | +This is [an unofficial template](#how-is-this-different-from-the-official-component-template) meant to ease the development of components for [Astro](https://astro.build/) that are intended for distribution. It does so by providing you with: |
| 4 | + |
| 5 | +- A clear default directory structure |
| 6 | +- Proper TypeScript settings for working with Astro |
| 7 | +- Default settings for ESLint, Prettier and EditorConfig inspired by the formatting used in the Astro project itself (also, [the config files are typed 👀](https://princesseuh.netlify.app/article/youshouldtypeyourconfigfiles/)) |
| 8 | +- Ready-to-use testing tools powered by the libraries also used by the Astro project (Mocha and Chai), also contains [astro-component-tester](https://github.com/Princesseuh/astro-component-tester) to help you test the output of your component(s) |
| 9 | +- Preconfigured VS Code workspace settings file with settings meant to make development cozy and nice |
| 10 | +- Use a example folder to help previewing the Component without npm link |
| 11 | + |
| 12 | +Hopefully, all of this together will provide you with a fun and comfortable development environnement for working on your Astro component! 🚀 Also, never forget that this is only a template to get you started, if you don't agree with any of the choices made, feel free to change it to fit your project better! |
| 13 | + |
| 14 | +**⚠️ Don't forget:** You should edit `package.json` with the info relevant to your project, such as a proper `name`, a license, a link to the repository for the npm website and other settings. You should also adjust the Astro `peerDependency` to the lowest version of Astro you support. |
| 15 | + |
| 16 | +## Folder Structure |
| 17 | + |
| 18 | +```plaintext |
| 19 | +├── .vscode/ # VS Code settings folder |
| 20 | +│ ├── settings.json # Workspace settings |
| 21 | +│ └── extensions.json # Recommended extensions to install |
| 22 | +├── example/ # Preview Your component here |
| 23 | +├── src/ # Your component source code |
| 24 | +│ ├── Component.astro # Example component file |
| 25 | +│ └── main.ts # Example source code file |
| 26 | +├── test/ # Your component tests |
| 27 | +│ └── example.test.js # Example tests |
| 28 | +└── index.ts # Should contain all the exports your component provide to users |
| 29 | +``` |
| 30 | + |
| 31 | +ESLint, Prettier and EditorConfig settings are respectively located in the following files: `.eslintrc.js`, `.prettierrc.js` and `.editorconfig` at the root of this template project. |
| 32 | + |
| 33 | +## Commands |
| 34 | + |
| 35 | +The following npm scripts are provided to lint and format your project: |
| 36 | + |
| 37 | +| Command | Action | |
| 38 | +| :--------------- | :------------------------------------------------------------ | |
| 39 | +| `npm run test` | Run tests using Mocha | |
| 40 | +| `npm run format` | Format your project using Prettier, this edits files in-place | |
| 41 | +| `npm run lint` | Lint your project using ESLint | |
| 42 | +| `npm run dev` | Run dev inside example project | |
| 43 | + |
| 44 | +In VS Code, you can access those commands in the Explorer in the `NPM Scripts` section. |
| 45 | + |
| 46 | +## Frequently asked questions |
| 47 | + |
| 48 | +### How is this different from [the official component template](https://github.com/withastro/astro/tree/main/examples/component)? |
| 49 | + |
| 50 | +At the end of the day, they both have the same goal: Giving you a template to start from to build a component for Astro. However, they have slightly different philosophies. |
| 51 | + |
| 52 | +Notably, the official template uses a mono-repo structure, whereas this template uses a normal, straightforward repo. Additionally, this template is a bit more opinionated than the official one, giving you preconfigured support for ESLint, Prettier, VS Code and EditorConfig, as well as testing support. |
| 53 | + |
| 54 | +It's up to you to choose which one you prefer, they're both good options! |
| 55 | + |
| 56 | +### How do I try my component in development? |
| 57 | + |
| 58 | +> `npm` is used here for brevity, the same concept applies to other package managers! |
| 59 | +
|
| 60 | +This template is a normal npm package, which mean that you can install it as a local folder or using [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link). |
| 61 | + |
| 62 | +For example, with the following folder structure: |
| 63 | + |
| 64 | +```plaintext |
| 65 | +├── component/ # Your component using this template |
| 66 | +└── project/ # A standard Astro project |
| 67 | +``` |
| 68 | + |
| 69 | +You can go into `project` and type the following command: `npm link ../component`. Changes to your component will be automatically reflected in your Astro project! |
| 70 | + |
| 71 | +### Which package manager should I use? |
| 72 | + |
| 73 | +The one you prefer! This template makes no assumption. |
| 74 | + |
| 75 | +The only package-manager-related thing in this repo is that the prettier plugin has the proper configuration needed to work with pnpm (but it works with the other too, pnpm just needs [additional settings](https://github.com/withastro/prettier-plugin-astro#pnpm-support)). |
0 commit comments