{"id":21645334,"url":"https://github.com/filrak/astro-layers","last_synced_at":"2025-04-11T18:43:38.332Z","repository":{"id":263403912,"uuid":"889135063","full_name":"filrak/astro-layers","owner":"filrak","description":"This package allows you to create multiple layers of files that override your base Astro application. Similarly to Nuxt Layers.","archived":false,"fork":false,"pushed_at":"2024-12-09T20:50:02.000Z","size":202,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T05:00:49.986Z","etag":null,"topics":["astrojs","inheritance","javascript","layers","overrides","typescript","withastro"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filrak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-15T17:17:18.000Z","updated_at":"2024-12-09T20:50:05.000Z","dependencies_parsed_at":"2024-11-18T11:45:41.371Z","dependency_job_id":"92dc8de2-c4e9-46e7-a576-866adc94dec4","html_url":"https://github.com/filrak/astro-layers","commit_stats":null,"previous_names":["filrak/astro-layers"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filrak%2Fastro-layers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filrak%2Fastro-layers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filrak%2Fastro-layers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filrak%2Fastro-layers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filrak","download_url":"https://codeload.github.com/filrak/astro-layers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248461065,"owners_count":21107599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astrojs","inheritance","javascript","layers","overrides","typescript","withastro"],"created_at":"2024-11-25T05:55:13.060Z","updated_at":"2025-04-11T18:43:38.324Z","avatar_url":"https://github.com/filrak.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astro Layers\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![bundle][bundle-src]][bundle-href]\n[![License][license-src]][license-href]\n\n\u003e Extend and override any Astro project files using a layered architecture - perfect for themes, white-labeling, and feature variations.\n\nThis package allows you to create multiple layers of files that override your base Astro application, similarly on how ti works at [Nuxt.js](https://nuxt.com/docs/getting-started/layers). Think of it like CSS cascading - each layer can override any file from your source code or previous layers, while keeping the rest intact. This includes pages, components, layouts, styles, public assets, and any other project files.\n\n**Key Features:**\n- 🎨 Perfect for theming and white-labeling\n- 🔄 Override any file while keeping others\n- 📁 Simple file-based configuration\n\nFor example, you can have a base e-commerce site and create different layers for:\n- Different brand themes (colors, logos, layouts)\n- Feature variations (basic/premium)\n- Client-specific customizations\n- Regional adaptations (localized assets and content)\n\n## Install\n\nInstall the plugin using your preferred package manager:\n```bash\npnpm install astro-layers\n```\n\nAdd the plugin to your `astro.config.mjs`:\n```js\nimport layers from 'astro-layers'\n\nexport default defineConfig({\n  plugins: [layers()],\n  // ...\n})\n```\n\nAdd `.layers` to your `.gitignore`:\n```bash\n# Astro Layers\n.layers\n```\n\nNow, create a `layers` directory in the root of your project and add some layers to it. Every file you put in a layer will override the default one in `src` folder.\n\n```\nproject-root/\n  layers/\n    layer-1/\n      pages/\n        index.astro # This will override default index.astro\n  src/\n    pages/\n      index.astro\n```\n\n## Layer Priority\n\nLayers are processed in alphabetical order. To control the priority, prefix your layer directories with numbers:\n\n```\nyour-project/\n├── layers/\n│   ├── 1.base/\n│   │   └── pages/\n│   │       └── index.astro\n│   ├── 2.theme/\n│   │   └── pages/\n│   │       └── index.astro\n│   └── 3.premium/\n│       └── pages/\n│           └── index.astro\n└── src/\n    └── pages/\n        └── index.astro\n```\n\nIn this example:\n- `1.base` will be checked first\n- `2.theme` will be checked second\n- `3.premium` will be checked last\n\nThis naming convention makes it easy to:\n- Understand the layer priority at a glance\n- Insert new layers between existing ones (e.g., `1.5.feature`)\n- Maintain a clear loading order without additional configuration\n\n### Example Use Cases\n\n```\nlayers/\n├── 1.base/          # Base components and layouts\n├── 2.theme/         # Theme-specific overrides\n├── 3.features/      # Feature-specific changes\n└── 4.customization/ # Customer-specific customizations\n```\n\n## External Layers\n\nYou can use layers from external sources like npm packages or git repositories. External layers follow the same naming convention as local layers to control priority.\n\n### Configuration\n\nConfigure external layers in your `astro.config.mjs`:\n\n```js\nimport layers from 'astro-layers'\n\nexport default defineConfig({\n  plugins: [\n    layers({\n      external: {\n        '1.base-theme': 'npm:astro-base-theme',\n        '2.premium': 'git:username/repo',\n        '3.custom': 'git:username/repo#branch'\n      }\n    })\n  ],\n})\n```\n\nThe keys (e.g., `1.base-theme`) determine the layer's priority, following the same numbering convention as local layers. Sources can be prefixed with:\n- `npm:` for npm packages\n- `git:` for GitHub repositories\n\n\u003e **Important:** External layers must only contain a `src` directory structure as Astro Layers only overrides files within the `src` folder. Any other files or directories will be ignored.\n\n### Layer Priority Example\n\n```\nyour-project/\n├── layers/\n│   ├── 1.core/\n│   └── 4.customization/\n└── .layers/\n    └── .external/\n        ├── 2.base-theme/    # from npm:astro-base-theme\n        └── 3.premium/       # from git:username/repo\n```\n\nIn this example, layers will be applied in this order:\n1. Local `1.core`\n2. External `2.base-theme`\n3. External `3.premium`\n4. Local `4.customization`\n\n## Credits\n\nWhile the original idea for this package is originating from [article](https://vueschool.io/articles/vuejs-tutorials/build-file-based-theme-inheritance-module-in-nuxt/) I wrote long time ago on Vue School, the name is borrowed from [Nuxt.js Layers](https://nuxt.com/docs/getting-started/layers).\n\nHuge thanks to [Anthony Fu](https://github.com/antfu) for creating amazing [TS library starter](https://github.com/antfu/starter-ts) that this package is using.\n\n## License\n\n[MIT](./LICENSE) License © 2024-PRESENT [Filip Rakowski](https://github.com/filrak)\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/astro-layers?style=flat\u0026colorA=080f12\u0026colorB=1fa669\n[npm-version-href]: https://npmjs.com/package/astro-layers\n[npm-downloads-src]: https://img.shields.io/npm/dm/astro-layers?style=flat\u0026colorA=080f12\u0026colorB=1fa669\n[npm-downloads-href]: https://npmjs.com/package/astro-layers\n[bundle-src]: https://img.shields.io/bundlephobia/minzip/astro-layers?style=flat\u0026colorA=080f12\u0026colorB=1fa669\u0026label=minzip\n[bundle-href]: https://bundlephobia.com/result?p=astro-layers\n[license-src]: https://img.shields.io/github/license/antfu/astro-layers.svg?style=flat\u0026colorA=080f12\u0026colorB=1fa669\n[license-href]: https://github.com/antfu/astro-layers/blob/main/LICENSE\n[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat\u0026colorA=080f12\u0026colorB=1fa669\n[jsdocs-href]: https://www.jsdocs.io/package/astro-layers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilrak%2Fastro-layers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilrak%2Fastro-layers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilrak%2Fastro-layers/lists"}