Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/davidenke/astro-decap-collection
Derive Astro collection schemata from Decap configs.
https://github.com/davidenke/astro-decap-collection
Last synced: about 1 month ago
JSON representation
Derive Astro collection schemata from Decap configs.
- Host: GitHub
- URL: https://github.com/davidenke/astro-decap-collection
- Owner: davidenke
- License: mit
- Created: 2024-10-19T21:42:35.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2024-10-21T15:37:48.000Z (2 months ago)
- Last Synced: 2024-10-21T21:47:03.460Z (2 months ago)
- Language: TypeScript
- Size: 1.86 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Astro Decap Collection
Derive [Astro content collection](https://docs.astro.build/en/guides/content-collections/) schemata from [Decap collection configs](https://decapcms.org/docs/configuration-options/#collections).
The procedure is to transform a Decap config into a [Zod schema](https://zod.dev/?id=basic-usage) by mapping the [Decap widget fields](https://decapcms.org/docs/widgets/) with custom [transformers](https://github.com/davidenke/astro-decap-collection/tree/main/src/transformers/).
> A demo application using the transforms to convert in the browser can be [found here](https://davidenke.github.io/astro-decap-collection).
## Installation
```bash
npm i -D astro-decap-collection
# or
pnpm add -D astro-decap-collection
# or
yarn add -D astro-decap-collection
```
## Usage
This module can either be used as a CLI tool or as a programmatic library.
| cli | programmatic |
| ----------------------------------------------------------- | ------------------------------------------------------------------- |
| 1. Run cli tool to generate the zod schema | 1. Load or import your Decap config file manually |
| 2. Load the generated schema in the Astro collection config | 2. Transform Decap config into zod schema |
| | 3. Provide the zod schema at runtime in the Astro collection config |
### Cli usage
Transform the Decap config at build time and use the generated Zod schema. This allows Astro to validate the given data and provides types as well.
> This is the recommended way to use this module.
| Option | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `--config`, `-c` | Path to the Decap YML config file, can be a [glob pattern](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax) |
| `--target`, `-t` | Path to the Astro content directory to write to |
| `--naming`, `-n` | Naming pattern of the created file [with placeholders](https://github.com/davidenke/astro-decap-collection?tab=readme-ov-file#placeholders) |
| `--watch`, `-w` | Watch the config file for changes |
_The name of the target file will be `config..ts` by default, using the collection name from the Decap config._\
_This can be configured with the [`--naming` option placeholders](https://github.com/davidenke/astro-decap-collection?tab=readme-ov-file#placeholders)._
> Config paths can be provided as positionals, thus the `--config` flag is optional.
```bash
# astro-decap-collection, adc - Binary name
# --config, -c - Decap YML config file path to read from
# --target, -t - Astro content directory path to write to
# --watch, -w - Use watch mode
# full command:
astro-decap-collection --config ./public/admin/config.yml --target ./src/content --watch
# or with shorthands and positionals:
adc -t ./src/content -w ./public/admin/config.yml
# or with glob pattern:
adc -t ./src/content -w ./public/collections/*.yml
```
> The cli command should be run at least before every `astro build`.
Then, the generated schema can be used in the [Astro collection config](https://docs.astro.build/en/guides/content-collections/#defining-collections).
```typescript
import { defineCollection } from 'astro:content';
import { prepareSchema } from 'astro-decap-collection';
// grab generated schema
import { schema } from './config.blog.ts';
// define the collection
// https://docs.astro.build/en/guides/content-collections/#defining-collections
export const collections = {
blog: defineCollection(prepareSchema(schema)),
// ... or without the convenience wrapper
blog: defineCollection({ type: 'content', schema }),
};
```
#### Placeholders
The `--naming` option can be used to define a naming pattern for the generated file.\
For the time being, the following placeholders are supported:
- `%%name%%` - The name of the collection from the Decap config
### Programmatic usage
This wont get you types, but you can still validate content against the schema.
```typescript
import {
getCollection,
loadDecapConfig,
prepareSchema,
transformCollection,
} from 'astro-decap-collection';
import { defineCollection, z as zod } from 'astro:content';
import { fileURLToPath } from 'node:url';
// load Decap config and transform it at runtime
const configURL = fileURLToPath(new URL('../../public/admin/config.yml', import.meta.url));
const config = await loadDecapConfig(configURL);
const collection = getCollection(config, 'blog')!;
const schema = await transformCollection(collection, { zod });
export const collections = {
blog: defineCollection(prepareSchema(schema.runtime)),
};
```
## Local development
Run a local tsx compiler in watch mode
```bash
npx -y tsx watch src/cli.ts -c public/examples/blog.yml -t tmp -w
```