Skip to main content

Introducing astro-layouts, my first npm package

The author of this blog smiling

Kevin Zuniga Cuellar @kevinzunigacuel

The logo of Astro and npm
Last updated: June 4, 2023

I’m excited to announce my first npm package, astro-layouts. This package injects a layout property into MD and MDX files’ frontmatter, making it easier to use layouts in Astro without the need to define them for each page in the frontmatter.

Idea and Motivation

I came up with the idea for this package while helping people in the Astro Discord server. I noticed that many users were struggling to define layouts, especially when dealing with numerous pages. To simplify the process, I decided to create a package that would allow them to define layouts from the Astro config file using glob patterns. With this approach, users could define a layout once and use it across multiple pages.

How It Works

The package utilizes glob patterns to match pages with their respective layouts. It then injects the layout property into the frontmatter of each page. The package leverages picomatch in the background to perform the glob pattern matching.


To install the package, run the following command:

Terminal window
npm install astro-layouts


To use the package, add it to the Astro config file in the remark plugin section. Here’s an example of an astro.config.mjs file:

import { defineConfig } from "astro/config";
import astroLayouts from "astro-layouts";
const layoutOptions = {
"pages/**/*": "/src/layouts/Layout.astro",
export default defineConfig({
markdown: {
remarkPlugins: [[astroLayouts, layoutOptions]],

In the layoutOptions object, you define the glob pattern and the layout to be used. The key represents the glob pattern for selecting files, while the value represents the absolute path to the layout component.

You can be as specific as needed with the glob patterns. Here are some examples:

You can target any file within the src folder. For instance, if your content resides in the src/markdown folder, you can use the following configuration:

const layoutOptions = {
"content/**/*": "/src/layouts/Layout.astro",

If you have aliases defined in your tsconfig.json file, you can use them to create shorter layout paths. Here’s an example of a tsconfig.json file:

"extends": "astro/tsconfigs/base",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@layouts/*": ["src/layouts/*"]

Then you can use aliases in the layoutOptions

const layoutOptions = {
"pages/**/*": "@layouts/Layout.astro",

Final thoughts

I hope you find this package useful. If you have any questions or suggestions, feel free to raise an issue on GitHub. I would appreciate any feedback. If you like the package, please consider giving it a star.

Writing this package was a lot of fun, and it provided me with valuable insights into the workings of npm packages and their publication process. I’m excited to create more packages in the future. Thank you for reading!