Integration Collections

Installing the dependency

npm

npm i @inox-tools/content-utils

yarn

yarn add @inox-tools/content-utils

pnpm

pnpm add @inox-tools/content-utils

Collection Injection

Sometimes an integration would prefer to accept content or configurations in the form of content/data collections. This can be useful when injecting dynamic pages that require specific field of an integration or when configuring a theme.

injectCollections

AIK-style utility for integrations to declare their own content collections. It accepts an entrypoint which should have the same exports as the src/content/config.ts would for a normal collection.

Tip

The entrypoint should be resolvable from the root of the Astro project, so if the integration is provided as a package remember to export the file in your package.json.

integration.ts

import { defineIntegration } from 'astro-integration-kit';
import { injectCollections } from '@inox-tools/content-utils';

export default defineIntegration({
  name: 'my-integration',
  setup: () => ({
    hooks: {
      'astro:config:setup': (params) => {
        injectCollections(params, {
          entrypoint: '@my/package/collections',
        });
      },
    },
  }),
});

Additionally, you can provide a seedTemplateDirectory along with your entrypoint. If you do, a call to seedCollections is implied using that path the template.

integration.ts

import { defineIntegration } from 'astro-integration-kit';
import { injectCollections } from '@inox-tools/content-utils';

export default defineIntegration({
  name: 'my-integration',
  setup: () => {
    const { resolve } = createResolver(import.meta.url);

    return  {
      hooks: {
        'astro:config:setup': (params) => {
          injectCollections(params, {
            entrypoint: '@my/package/collections',
            seedTemplateDirectory: resolve('./collectionTemplates'),
          });
        },
      },
    }
  }),
});

@it-astro:content virtual module

This virtual module provides the same API as astro:content, with the exception of defineCollection. Instead, defineCollection creates a FancyCollection, that can be extended by users of your integration.

For integration authors, it is a drop-in replacement.

integration/collection.ts

import { defineCollection, z } from 'astro:content';
import { defineCollection, z } from '@it-astro:content';

export const collections = {
  darculaColors: defineCollection({
    type: 'data',
    schema: z.object({
      light: z.string(),
      dark: z.string(),
    }),
  }),
};

Users of your integration would then be able to extend the schema like so:

src/content/config.ts

import { defineCollection, z } from 'astro:content';
import { collections as integrationCollections } from '@my/integration/collections';

export const collections = {
  darculaColors: integrationCollections.darculaColors({
    extend: z.object({
      accent: z.string(),
    }),
  }),
};

Collection Seeding

If you want to provide some initial content for collections used by your integration so your users know where to start, you can provide a seed for your collections.

seedCollections

AIK-style utility for integrations to declare a seed for collections.

It received the absolute path to a directory that should contain collections in the same structure as expected by Astro, each folder inside of it should have the name of the collection and it’s contents should follow a set schema.

For example, if you have the following file structure:

• integration.ts
• DirectorycollectionTemplates

  • DirectorydarculaColors

    • blog.json
    • landingPage.json

You can declare the seed like so:

integration.ts

import { defineIntegration, createResolver } from 'astro-integration-kit';
import { seedCollections } from '@inox-tools/content-utils';

export default defineIntegration({
  name: 'my-integration',
  setup: () => {
    const { resolve } = createResolver(import.meta.url);

    return {
      hooks: {
        'astro:config:setup': (params) => {
          seedCollections(params, {
            templateDirectory: resolve('./collectionTemplates'),
          });
        },
      },
    };
  },
});