feat: useDocuments composable as a faster and more convenient version of import.meta.globEager

ElMassimo commented 2 years ago

Description 📖

This pull request adds a new useDocuments composable that can be used to get a reference to local files, and read their frontmatter and meta, as well as render them as components.

const posts = useDocuments('~/pages/posts')

You can use the experimental ref sugar if you need to access it in scripts (for example, to sort the documents):

export function usePosts () {
  const posts = $(useDocuments('~/pages/posts'))
  return computed(() => posts.sort(byDate))
}

Provide a glob pattern if you need to narrow down the results:

useDocuments('~/pages/(posts|articles)/*.{md,mdx}')

Features ✨

Significantly faster than import.meta.glob, frontmatter is cached and reused
Can use any aliases you have defined in Vite
Very fine-grained HMR, updates are instant

HMR 🚀

Changes to the frontmatter are instantly reflected
HMR of each component works as expected
When files matching the pattern are added or removed, it updates without reloading the page

Typescript 💪🏼

The API is fully typed, and all the frontmatter and meta properties will show up including any extensions you have added in PageMeta or PageFrontmatter.

function usePosts () {
  return useDocuments<Post>('~/pages/posts')
}

// typeof usePosts === ComputedRef<Post[]>

Screenshots 📷

netlify[bot] commented 2 years ago

✔️ Deploy Preview for iles-docs canceled.

🔨 Explore the source changes: c8755a88f57bc2945c8bcc3e3626701c3972e877

🔍 Inspect the deploy log: https://app.netlify.com/sites/iles-docs/deploys/61be5a1e7eee0d000802f01d

netlify[bot] commented 2 years ago

✔️ Deploy Preview for the-vue-point-with-iles canceled.

🔨 Explore the source changes: c8755a88f57bc2945c8bcc3e3626701c3972e877

🔍 Inspect the deploy log: https://app.netlify.com/sites/the-vue-point-with-iles/deploys/61be5a1eace8570007fd0d26

cloudflare-pages[bot] commented 2 years ago

Deploying with Cloudflare Pages

Latest commit:	`c8755a8`
Status:	✅ Deploy successful!
Preview URL:	https://9d277884.iles.pages.dev

View logs

ElMassimo / iles