Skip to content

Commit 7946f40

Browse files
committed
docs: readme and changelog
1 parent 6a13c1a commit 7946f40

File tree

2 files changed

+150
-0
lines changed

2 files changed

+150
-0
lines changed

CHANGELOG.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.1.0-beta.1] - 2025-11-28
9+
10+
### Added
11+
12+
- **Custom ID Generator** - Added `idGenerator` option to `StrapiLoaderOptions` allowing custom ID generation from item data instead of using Strapi's `documentId` (#17)
13+
- **Multiple Collections from Same Endpoint** - Added `collectionName` option to create multiple collections from the same Strapi content type with different configurations (#18)
14+
- **Locale Support** - Added `locale` option supporting both single locale (string) and multiple locales (array) for i18n implementations (#19)
15+
- Single locale: Fetch content for one specific language
16+
- Multiple locales: Fetch all specified languages with locale-prefixed IDs
17+
- Automatic `_locale` field added to stored items
18+
- Comprehensive test suite with 27 new tests covering all new features
19+
20+
### Changed
21+
22+
- `StrapiLoaderOptions` interface extended with new optional fields: `collectionName`, `idGenerator`, and `locale`
23+
- `StrapiCollection` interface extended to support new loader options
24+
- `generateCollection` function updated to pass new options to loader
25+
26+
### Fixed
27+
28+
- N/A
29+
30+
### Breaking Changes
31+
32+
- None - fully backward compatible with existing implementations
33+
34+
## [1.0.x] - 2024-XX-XX
35+
36+
### Initial Release
37+
38+
- Basic Strapi loader functionality
39+
- Automatic data loading from Strapi Content API
40+
- Query, filtering and population capabilities
41+
- Authorization token support
42+
- Astro collections system integration
43+
- TypeScript typing support
44+

README.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@ yarn add @sensinum/astro-strapi-loader
5555
* Authorization token support
5656
* Astro collections system integration
5757
* TypeScript typing
58+
* **🆕 Custom ID generation** - Generate collection IDs from custom fields (e.g., slugs)
59+
* **🆕 Multiple collections** - Create multiple collections from same endpoint
60+
* **🆕 i18n support** - Built-in locale support for multilingual content
5861

5962
## 🖥️ Usage
6063

@@ -131,9 +134,112 @@ const myCollection = await fetchContent({
131134
|--------|------|----------|-------------|
132135
| `url` | `string` | Yes | Strapi API URL |
133136
| `token` | `string` | No | Strapi API access token |
137+
| `collectionName` | `string` | No | Custom collection name (for multiple collections from same endpoint) |
138+
| `idGenerator` | `function` | No | Custom function to generate IDs from item data |
139+
| `locale` | `string \| string[]` | No | Single locale or array of locales for i18n support |
134140

135141
> **⚠️ Note:** The token must have **read access** to both the **Content API** and the **Content-Type Builder API** *(ONLY to the "Get Content Types" endpoint)*.
136142
143+
### Advanced Usage Examples
144+
145+
#### Custom ID Generation
146+
147+
Use slugs or custom fields as collection IDs instead of Strapi's `documentId`:
148+
149+
```typescript
150+
import { strapiLoader } from '@sensinum/astro-strapi-loader';
151+
import { defineCollection, z } from 'astro:content';
152+
153+
const pages = defineCollection({
154+
loader: strapiLoader('pages', {
155+
url: import.meta.env.STRAPI_URL,
156+
token: import.meta.env.STRAPI_TOKEN,
157+
idGenerator: (data) => data.slug as string
158+
}),
159+
schema: z.object({
160+
slug: z.string(),
161+
title: z.string(),
162+
content: z.string()
163+
})
164+
});
165+
166+
// Now you can use: getEntry('pages', 'about-us')
167+
```
168+
169+
#### Multiple Collections from Same Endpoint
170+
171+
Create separate collections for different languages from the same Strapi content type:
172+
173+
```typescript
174+
const pagesEN = defineCollection({
175+
loader: strapiLoader('pages', {
176+
url: import.meta.env.STRAPI_URL,
177+
token: import.meta.env.STRAPI_TOKEN,
178+
collectionName: 'pagesEN',
179+
locale: 'en'
180+
}),
181+
schema: pageSchema
182+
});
183+
184+
const pagesDE = defineCollection({
185+
loader: strapiLoader('pages', {
186+
url: import.meta.env.STRAPI_URL,
187+
token: import.meta.env.STRAPI_TOKEN,
188+
collectionName: 'pagesDE',
189+
locale: 'de'
190+
}),
191+
schema: pageSchema
192+
});
193+
194+
export const collections = { pagesEN, pagesDE };
195+
```
196+
197+
#### Multiple Locales in Single Collection
198+
199+
Fetch all language versions in one collection:
200+
201+
```typescript
202+
const pagesMultilang = defineCollection({
203+
loader: strapiLoader('pages', {
204+
url: import.meta.env.STRAPI_URL,
205+
token: import.meta.env.STRAPI_TOKEN,
206+
locale: ['en', 'de', 'fr'] // Array of locales
207+
}),
208+
schema: z.object({
209+
title: z.string(),
210+
content: z.string(),
211+
_locale: z.string() // Automatically added by loader
212+
})
213+
});
214+
215+
// Access by locale-prefixed ID
216+
const page = await getEntry('pagesMultilang', 'en:documentId');
217+
218+
// Or filter by locale
219+
const allPages = await getCollection('pagesMultilang');
220+
const enPages = allPages.filter(p => p.data._locale === 'en');
221+
```
222+
223+
#### Combining All Features
224+
225+
```typescript
226+
const blogMultilang = defineCollection({
227+
loader: strapiLoader('blog-posts', {
228+
url: import.meta.env.STRAPI_URL,
229+
token: import.meta.env.STRAPI_TOKEN,
230+
collectionName: 'blogAllLanguages',
231+
locale: ['en', 'de', 'fr'],
232+
idGenerator: (data) => data.slug as string
233+
}, {
234+
sort: ['publishedAt:desc'],
235+
filters: { status: { $eq: 'published' } }
236+
}),
237+
schema: blogSchema
238+
});
239+
240+
// Access: getEntry('blogAllLanguages', 'en:my-post-slug')
241+
```
242+
137243
### Query Options
138244

139245
| Option | Type | Description | Documentation |

0 commit comments

Comments
 (0)