astro-loader-pocketbase 0.5.0-rc.1 → 0.5.0

package/README.md

@@ -9,18 +9,6 @@
 
 This package is a simple loader to load data from a PocketBase database into Astro using the [Astro Loader API](https://5-0-0-beta.docs.astro.build/en/reference/loader-reference/) introduced in Astro 5.
 
-> [!WARNING]
-> This package is still under development.
-> It will have a first stable release when Astro 5 is released.
-> Until then, **breaking changes can occur at any time**.
-
-## Compatibility
-
-| Loader version                                                               | Astro version | PocketBase version |
-| ---------------------------------------------------------------------------- | ------------- | ------------------ |
-| >= 0.5.0                                                                     | >= 5.0.0-beta | >= 0.23.0          |
-| <= [0.4.0](https://github.com/pawcoding/astro-loader-pocketbase/tree/v0.4.0) | >= 5.0.0-beta | < 0.23.0           |
-
 ## Basic usage
 
 In your content configuration file, you can use the `pocketbaseLoader` function to use your PocketBase database as a data source.
@@ -39,30 +27,12 @@ const blog = defineCollection({
 export const collections = { blog };
 ```
 
+By default, the loader will only fetch entries that have been modified since the last build.
 Remember that due to the nature [Astros Content Layer lifecycle](https://astro.build/blog/content-layer-deep-dive#content-layer-lifecycle), the loader will **only fetch entries at build time**, even when using on-demand rendering.
 If you want to update your deployed site with new entries, you need to rebuild it.
 
 <sub>When running the dev server, you can trigger a reload by using `s + enter`.</sub>
 
-## Incremental builds
-
-Since PocketBase 0.23.0, the `updated` field is not mandatory anymore.
-This means that the loader can't automatically detect when an entry has been modified.
-To enable incremental builds, you need to provide the name of a field in your collection that stores the last update date of an entry.
-
-```ts
-const blog = defineCollection({
-  loader: pocketbaseLoader({
-    ...options,
-    updatedField: "<field-in-collection>"
-  })
-});
-```
-
-When this field is provided, the loader will only fetch entries that have been modified since the last build.
-Ideally, this field should be of type `autodate` and have the value "Update" or "Create/Update" in the PocketBase dashboard.
-This ensures that the field is automatically updated when an entry is modified.
-
 ## Entries
 
 After generating the schema (see below), the loader will automatically parse the content of the entries (e.g. transform ISO dates to `Date` objects, coerce numbers, etc.).
@@ -76,7 +46,7 @@ This content will then be used when calling the `render` function of [Astros con
 const blog = defineCollection({
   loader: pocketbaseLoader({
     ...options,
-    contentFields: "<field-in-collection>"
+    content: "<field-in-collection>"
   })
 });
 ```
@@ -92,6 +62,25 @@ While the API only returns the filenames of these images and files, the loader w
 This doesn't mean that the files are downloaded during the build process.
 But you can directly use these URLs in your Astro components to display images or link to the files.
 
+### Custom ids
+
+By default, the loader will use the `id` field of the collection as the unique identifier.
+If you want to use another field as the id, e.g. a slug of the title, you can specify this field via the `id` option.
+
+```ts
+const blog = defineCollection({
+  loader: pocketbaseLoader({
+    ...options,
+    id: "<field-in-collection>"
+  })
+});
+```
+
+Please note that the id should be unique for every entry in the collection.
+The loader will also automatically convert the value into a slug to be easily used in URLs.
+It's recommended to use e.g. the title of the entry to be easily searchable and readable.
+**Do not use e.g. rich text fields as ids.**
+
 ## Type generation
 
 The loader can automatically generate types for your collection.
@@ -100,16 +89,14 @@ These types can be generated in two ways:
 
 ### Remote schema
 
-To use the lice remote schema, you need to provide superuser credentials for the PocketBase instance.
+To use the lice remote schema, you need to provide the email and password of an admin of the PocketBase instance.
 
 ```ts
 const blog = defineCollection({
   loader: pocketbaseLoader({
     ...options,
-    superuserCredentials: {
-      email: "<superuser-email>",
-      password: "<superuser-password>"
-    }
+    adminEmail: "<admin-email>",
+    adminPassword: "<admin-password>"
   })
 });
 ```
@@ -118,7 +105,7 @@ Under the hood, the loader will use the [PocketBase API](https://pocketbase.io/d
 
 ### Local schema
 
-If you don't want to provide superuser credentials (e.g. in a public repository), you can also provide the schema manually via a JSON file.
+If you don't want to provide the admin credentials (e.g. in a public repository), you can also provide the schema manually via a JSON file.
 
 ```ts
 const blog = defineCollection({
@@ -132,7 +119,7 @@ const blog = defineCollection({
 In PocketBase you can export the schema of the whole database to a `pb_schema.json` file.
 If you provide the path to this file, the loader will use this schema to generate the types locally.
 
-When superuser credentials are provided, the loader will **always use the remote schema** since it's more up-to-date.
+When admin credentials are provided, the loader will **always use the remote schema** since it's more up-to-date.
 
 ### Manual schema
 
@@ -141,25 +128,37 @@ This manual schema will **always override the automatic type generation**.
 
 ## All options
 
-| Option                 | Type                                  | Required | Description                                                                                                     |
-| ---------------------- | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| `url`                  | `string`                              | x        | The URL of your PocketBase instance.                                                                            |
-| `collectionName`       | `string`                              | x        | The name of the collection in your PocketBase instance.                                                         |
-| `contentFields`        | `string \| Array<string>`             |          | The field in the collection to use as content. This can also be an array of fields.                             |
-| `updatedField`         | `string`                              |          | The field in the collection that stores the last update date of an entry. This is used for incremental builds.  |
-| `superuserCredentials` | `{ email: string, password: string }` |          | The email and password of the superuser of the PocketBase instance. This is used for automatic type generation. |
-| `localSchema`          | `string`                              |          | The path to a local schema file. This is used for automatic type generation.                                    |
-| `jsonSchemas`          | `Record<string, z.ZodSchema>`         |          | A record of Zod schemas to use for type generation of `json` fields.                                            |
+| Option           | Type                          | Required | Description                                                                                                                         |
+| ---------------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `url`            | `string`                      | x        | The URL of your PocketBase instance.                                                                                                |
+| `collectionName` | `string`                      | x        | The name of the collection in your PocketBase instance.                                                                             |
+| `content`        | `string \| Array<string>`     |          | The field in the collection to use as content. This can also be an array of fields.                                                 |
+| `adminEmail`     | `string`                      |          | The email of the admin of the PocketBase instance. This is used for automatic type generation and access to private collections.    |
+| `adminPassword`  | `string`                      |          | The password of the admin of the PocketBase instance. This is used for automatic type generation and access to private collections. |
+| `id`             | `string`                      |          | The field in the collection to use as unique id. Defaults to `id`.                                              |
+| `localSchema`    | `string`                      |          | The path to a local schema file. This is used for automatic type generation.                                                        |
+| `jsonSchemas`    | `Record<string, z.ZodSchema>` |          | A record of Zod schemas to use for type generation of `json` fields.                                                                |
+| `forceUpdate`    | `boolean`                     |          | If set to `true`, the loader will fetch every entry instead of only the ones modified since the last build.                         |
 
 ## Special cases
 
-### Private collections and hidden fields
+### Private collections
 
-If you want to access a private collection or want to access hidden fields, you also need to provide superuser credentials.
+If you want to access a private collection, you also need to provide the admin credentials.
 Otherwise, you need to make the collection public in the PocketBase dashboard.
 
 Generally, it's not recommended to use private collections, especially when users should be able to see images or other files stored in the collection.
 
+### View collections
+
+Out of the box, the loader also supports collections with the type `view`, though with some limitations.
+To enable incremental builds, the loader needs to know when an entry has been modified.
+Normal `base` collections have a `updated` field that is automatically updated when an entry is modified.
+Thus, `view` collections that don't include this field can't be incrementally built but will be fetched every time.
+
+You can also alias another field as `updated` (as long as it's a date field) in your view.
+While this is possible, it's not recommended since it can lead to outdated data not being fetched.
+
 ### JSON fields
 
 PocketBase can store arbitrary JSON data in a `json` field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "0.5.0-rc.1",
+  "version": "0.5.0",
   "description": "A content loader for Astro that uses the PocketBase API",
   "license": "MIT",
   "author": "Luis Wolf <development@pawcode.de> (https://pawcode.de)",
@@ -24,7 +24,7 @@
     "@eslint/js": "^9.11.1",
     "@stylistic/eslint-plugin": "^2.8.0",
     "@types/node": "^22.7.4",
-    "astro": "^5.0.0-beta.2",
+    "astro": "^5.0.0-beta.6",
     "eslint": "^9.11.1",
     "globals": "^15.9.0",
     "husky": "^9.1.6",

package/src/cleanup-entries.ts

@@ -6,12 +6,12 @@ import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.
  *
  * @param options Options for the loader.
  * @param context Context of the loader.
- * @param superuserToken Superuser token to access all resources.
+ * @param adminToken Admin token to access all resources.
  */
 export async function cleanupEntries(
   options: PocketBaseLoaderOptions,
   context: LoaderContext,
-  superuserToken: string | undefined
+  adminToken: string | undefined
 ): Promise<void> {
   // Build the URL for the collections endpoint
   const collectionUrl = new URL(
@@ -19,10 +19,10 @@ export async function cleanupEntries(
     options.url
   ).href;
 
-  // Create the headers for the request to append the superuser token (if available)
+  // Create the headers for the request to append the admin token (if available)
   const collectionHeaders = new Headers();
-  if (superuserToken) {
-    collectionHeaders.set("Authorization", superuserToken);
+  if (adminToken) {
+    collectionHeaders.set("Authorization", adminToken);
   }
 
   // Prepare pagination variables
@@ -42,10 +42,10 @@ export async function cleanupEntries(
 
     // If the request was not successful, print the error message and return
     if (!collectionRequest.ok) {
-      // If the collection is locked, an superuser token is required
+      // If the collection is locked, an admin token is required
       if (collectionRequest.status === 403) {
         context.logger.error(
-          `(${options.collectionName}) The collection is not accessible without superuser rights. Please provide superuser credentials in the config.`
+          `The collection ${options.collectionName} is not accessible without an admin rights. Please provide an admin email and password in the config.`
         );
         return;
       }
@@ -53,7 +53,7 @@ export async function cleanupEntries(
       const reason = await collectionRequest
         .json()
         .then((data) => data.message);
-      const errorMessage = `(${options.collectionName}) Fetching ids failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
+      const errorMessage = `Fetching ids from ${options.collectionName} failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
       context.logger.error(errorMessage);
       return;
     }
@@ -74,7 +74,7 @@ export async function cleanupEntries(
   let cleanedUp = 0;
 
   // Get all ids of the entries in the store
-  const storedIds = context.store.keys();
+  const storedIds = context.store.values().map((entry) => entry.data.id) as Array<string>;
   for (const id of storedIds) {
     // If the id is not in the entries set, remove the entry from the store
     if (!entries.has(id)) {
@@ -86,7 +86,7 @@ export async function cleanupEntries(
   if (cleanedUp > 0) {
     // Log the number of cleaned up entries
     context.logger.info(
-      `(${options.collectionName}) Cleaned up ${cleanedUp} old entries.`
+      `Cleaned up ${cleanedUp} old entries for ${context.collection}`
     );
   }
 }

package/src/generate-schema.ts

@@ -13,13 +13,31 @@ import { transformFiles } from "./utils/transform-files";
 const BASIC_SCHEMA = {
   id: z.string(),
   collectionId: z.string().length(15),
-  collectionName: z.string()
+  collectionName: z.string(),
+  created: z.coerce.date(),
+  updated: z.coerce.date()
 };
 
+/**
+ * Basic schema for a view in PocketBase.
+ */
+const VIEW_SCHEMA = {
+  id: z.string(),
+  collectionId: z.string().length(15),
+  collectionName: z.string(),
+  created: z.preprocess((val) => val || undefined, z.optional(z.coerce.date())),
+  updated: z.preprocess((val) => val || undefined, z.optional(z.coerce.date()))
+};
+
+/**
+ * Types of fields that can be used as an ID.
+ */
+const VALID_ID_TYPES = ["text", "number", "email", "url", "date"];
+
 /**
  * Generate a schema for the collection based on the collection's schema in PocketBase.
  * By default, a basic schema is returned if no other schema is available.
- * If superuser credentials are provided, the schema is fetched from the PocketBase API.
+ * If admin credentials are provided, the schema is fetched from the PocketBase API.
  * If a path to a local schema file is provided, the schema is read from the file.
  *
  * @param options Options for the loader. See {@link PocketBaseLoaderOptions} for more details.
@@ -32,8 +50,6 @@ export async function generateSchema(
   // Try to get the schema directly from the PocketBase instance
   collection = await getRemoteSchema(options);
 
-  const hasSuperuserRights = !!collection || !!options.superuserCredentials;
-
   // If the schema is not available, try to read it from a local schema file
   if (!collection && options.localSchema) {
     collection = await readLocalSchema(
@@ -45,29 +61,47 @@ export async function generateSchema(
   // If the schema is still not available, return the basic schema
   if (!collection) {
     console.error(
-      `No schema available for "${options.collectionName}". Only basic types are available. Please check your configuration and provide a valid schema file or superuser credentials.`
+      `No schema available for ${options.collectionName}. Only basic types are available. Please check your configuration and provide a valid schema file or admin credentials.`
     );
-    // Return the basic schema since every collection has at least these fields
-    return z.object(BASIC_SCHEMA);
+    // Return the view schema since every collection has at least the view schema
+    return z.object(VIEW_SCHEMA);
   }
 
   // Parse the schema
-  const fields = parseSchema(
-    collection,
-    options.jsonSchemas,
-    hasSuperuserRights
-  );
+  const fields = parseSchema(collection, options.jsonSchemas);
+
+  // Check if custom id field is present
+  if (options.id) {
+    // Find the id field in the schema
+    const idField = collection.schema.find(
+      (field) => field.name === options.id
+    );
+
+    // Check if the id field is present and of a valid type
+    if (!idField) {
+      console.error(
+        `The id field "${options.id}" is not present in the schema of the collection "${options.collectionName}".`
+      );
+    } else if (!VALID_ID_TYPES.includes(idField.type)) {
+      console.error(
+        `The id field "${options.id}" for collection "${
+          options.collectionName
+        }" is of type "${
+          idField.type
+        }" which is not recommended. Please use one of the following types: ${VALID_ID_TYPES.join(
+          ", "
+        )}.`
+      );
+    }
+  }
 
   // Check if the content field is present
-  if (
-    typeof options.contentFields === "string" &&
-    !fields[options.contentFields]
-  ) {
+  if (typeof options.content === "string" && !fields[options.content]) {
     console.error(
-      `The content field "${options.contentFields}" is not present in the schema of the collection "${options.collectionName}".`
+      `The content field "${options.content}" is not present in the schema of the collection "${options.collectionName}".`
     );
-  } else if (Array.isArray(options.contentFields)) {
-    for (const field of options.contentFields) {
+  } else if (Array.isArray(options.content)) {
+    for (const field of options.content) {
       if (!fields[field]) {
         console.error(
           `The content field "${field}" is not present in the schema of the collection "${options.collectionName}".`
@@ -76,39 +110,18 @@ export async function generateSchema(
     }
   }
 
-  // Check if the updated field is present
-  if (options.updatedField) {
-    if (!fields[options.updatedField]) {
-      console.error(
-        `The field "${options.updatedField}" is not present in the schema of the collection "${options.collectionName}".\nThis will lead to errors when trying to fetch only updated entries.`
-      );
-    } else {
-      const updatedField = collection.fields.find(
-        (field) => field.name === options.updatedField
-      );
-      if (
-        !updatedField ||
-        updatedField.type !== "autodate" ||
-        !updatedField.onUpdate
-      ) {
-        console.warn(
-          `The field "${options.updatedField}" is not of type "autodate" with the value "Update" or "Create/Update".\nMake sure that the field is automatically updated when the entry is updated!`
-        );
-      }
-    }
-  }
+  // Use the corresponding base schema for the type of collection
+  // Auth collections are basically a superset of the basic schema.
+  const base = collection.type === "view" ? VIEW_SCHEMA : BASIC_SCHEMA;
 
   // Combine the basic schema with the parsed fields
   const schema = z.object({
-    ...BASIC_SCHEMA,
+    ...base,
     ...fields
   });
 
   // Get all file fields
-  const fileFields = collection.fields
-    .filter((field) => field.type === "file")
-    // Only show hidden fields if the user has superuser rights
-    .filter((field) => !field.hidden || hasSuperuserRights);
+  const fileFields = collection.schema.filter((field) => field.type === "file");
 
   if (fileFields.length === 0) {
     return schema;
@@ -116,6 +129,7 @@ export async function generateSchema(
 
   // Transform file names to file urls
   return schema.transform((entry) =>
+    // @ts-expect-error - `updated` and `created` are already transformed to dates
     transformFiles(options.url, fileFields, entry)
   );
 }

package/src/load-entries.ts

@@ -7,7 +7,7 @@ import { parseEntry } from "./utils/parse-entry";
  *
  * @param options Options for the loader.
  * @param context Context of the loader.
- * @param superuserToken Superuser token to access all resources.
+ * @param adminToken Admin token to access all resources.
  * @param lastModified Date of the last fetch to only update changed entries.
  *
  * @returns `true` if the collection has an updated column, `false` otherwise.
@@ -15,34 +15,35 @@ import { parseEntry } from "./utils/parse-entry";
 export async function loadEntries(
   options: PocketBaseLoaderOptions,
   context: LoaderContext,
-  superuserToken: string | undefined,
+  adminToken: string | undefined,
   lastModified: string | undefined
-): Promise<void> {
+): Promise<boolean> {
   // Build the URL for the collections endpoint
   const collectionUrl = new URL(
     `api/collections/${options.collectionName}/records`,
     options.url
   ).href;
 
-  // Create the headers for the request to append the superuser token (if available)
+  // Create the headers for the request to append the admin token (if available)
   const collectionHeaders = new Headers();
-  if (superuserToken) {
-    collectionHeaders.set("Authorization", superuserToken);
+  if (adminToken) {
+    collectionHeaders.set("Authorization", adminToken);
   }
 
   // Log the fetching of the entries
   context.logger.info(
-    `(${options.collectionName}) Fetching${
-      lastModified ? " modified" : ""
-    } data${lastModified ? ` starting at ${lastModified}` : ""}${
-      superuserToken ? " as superuser" : ""
-    }`
+    `Fetching${lastModified ? " modified" : ""} data for ${
+      context.collection
+    } from ${collectionUrl}${
+      lastModified ? ` starting at ${lastModified}` : ""
+    }${adminToken ? " with admin token" : ""}`
   );
 
   // Prepare pagination variables
   let page = 0;
   let totalPages = 0;
   let entries = 0;
+  let hasUpdatedColumn = !!lastModified;
 
   // Fetch all (modified) entries
   do {
@@ -50,8 +51,8 @@ export async function loadEntries(
     // If `lastModified` is set, only fetch entries that have been modified since the last fetch
     const collectionRequest = await fetch(
       `${collectionUrl}?page=${++page}&perPage=100${
-        lastModified && options.updatedField
-          ? `&sort=-${options.updatedField},id&filter=(${options.updatedField}>"${lastModified}")`
+        lastModified
+          ? `&sort=-updated,id&filter=(updated>"${lastModified}")`
           : ""
       }`,
       {
@@ -61,10 +62,10 @@ export async function loadEntries(
 
     // If the request was not successful, print the error message and return
     if (!collectionRequest.ok) {
-      // If the collection is locked, an superuser token is required
+      // If the collection is locked, an admin token is required
       if (collectionRequest.status === 403) {
         throw new Error(
-          `(${options.collectionName}) The collection is not accessible without superuser rights. Please provide superuser credentials in the config.`
+          `The collection ${options.collectionName} is not accessible without an admin rights. Please provide an admin email and password in the config.`
         );
       }
 
@@ -72,7 +73,7 @@ export async function loadEntries(
       const reason = await collectionRequest
         .json()
         .then((data) => data.message);
-      const errorMessage = `(${options.collectionName}) Fetching data failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
+      const errorMessage = `Fetching data from ${options.collectionName} failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
       throw new Error(errorMessage);
     }
 
@@ -81,12 +82,13 @@ export async function loadEntries(
 
     // Parse and store the entries
     for (const entry of response.items) {
-      await parseEntry(
-        entry,
-        context,
-        options.contentFields,
-        options.updatedField
-      );
+      await parseEntry(entry, context, options.id, options.content);
+
+      // Check if the entry has an `updated` column
+      // This is used to enable the incremental fetching of entries
+      if (!hasUpdatedColumn && "updated" in entry) {
+        hasUpdatedColumn = true;
+      }
     }
 
     // Update the page and total pages
@@ -97,8 +99,11 @@ export async function loadEntries(
 
   // Log the number of fetched entries
   context.logger.info(
-    `(${options.collectionName}) Fetched ${entries}${
-      lastModified ? " changed" : ""
-    } entries.`
+    `Fetched ${entries}${lastModified ? " changed" : ""} entries for ${
+      context.collection
+    }`
   );
+
+  // Return if the collection has an updated column
+  return hasUpdatedColumn;
 }

package/src/pocketbase-loader.ts

@@ -4,7 +4,7 @@ import { cleanupEntries } from "./cleanup-entries";
 import { generateSchema } from "./generate-schema";
 import { loadEntries } from "./load-entries";
 import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.type";
-import { getSuperuserToken } from "./utils/get-superuser-token";
+import { getAdminToken } from "./utils/get-admin-token";
 
 /**
  * Loader for collections stored in PocketBase.
@@ -15,37 +15,37 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
   return {
     name: "pocketbase-loader",
     load: async (context: LoaderContext): Promise<void> => {
-      // Get the date of the last fetch to only update changed entries.
-      let lastModified = context.meta.get("last-modified");
-
       // Check if the version has changed to force an update
       const lastVersion = context.meta.get("version");
       if (lastVersion !== packageJson.version) {
-        if (lastVersion) {
-          context.logger.info(
-            `PocketBase loader was updated from ${lastVersion} to ${packageJson.version}. All entries will be loaded again.`
-          );
-        }
+        context.logger.info(
+          `PocketBase loader was updated from ${lastVersion} to ${packageJson.version}. All entries will be loaded again.`
+        );
 
-        // Disable incremental builds and clear the store
-        lastModified = undefined;
-        context.store.clear();
+        options.forceUpdate = true;
       }
 
-      // Disable incremental builds if no updated field is provided
-      if (!options.updatedField) {
-        context.logger.info(
-          `(${options.collectionName}) No "updatedField" was provided. Incremental builds are disabled.`
-        );
-        lastModified = undefined;
+      // Get the date of the last fetch to only update changed entries.
+      // If `forceUpdate` is set to `true`, this will be `undefined` to fetch all entries again.
+      const lastModified = options.forceUpdate
+        ? undefined
+        : context.meta.get("last-modified");
+
+      // Get the `has-updated-column` meta to check if the collection has an updated column
+      let hasUpdatedColumn = context.meta.get("has-updated-column") === "true";
+
+      // Clear the store if we want to fetch all entries again
+      if (options.forceUpdate) {
+        context.store.clear();
       }
 
-      // Try to get a superuser token to access all resources.
+      // Try to get an admin token to access all resources.
       let token: string | undefined;
-      if (options.superuserCredentials) {
-        token = await getSuperuserToken(
+      if (options.adminEmail && options.adminPassword) {
+        token = await getAdminToken(
           options.url,
-          options.superuserCredentials,
+          options.adminEmail,
+          options.adminPassword,
           context.logger
         );
       }
@@ -56,7 +56,25 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
       }
 
       // Load the (modified) entries
-      await loadEntries(options, context, token, lastModified);
+      try {
+        hasUpdatedColumn = await loadEntries(
+          options,
+          context,
+          token,
+          // Only fetch entries that have been modified since the last fetch
+          // If the collection does not have an updated column, all entries will be fetched
+          hasUpdatedColumn ? lastModified : undefined
+        );
+      } catch (error) {
+        // Set the `has-updated-column` meta to `false` if an error occurred
+        // This will force the loader to fetch all entries again in the next run
+        context.meta.set("has-updated-column", `${false}`);
+
+        throw error;
+      }
+
+      // Set the `has-updated-column` meta to `true` if the collection has an updated column
+      context.meta.set("has-updated-column", `${hasUpdatedColumn}`);
 
       // Set the last modified date to the current date
       context.meta.set("last-modified", new Date().toISOString());

package/src/types/pocketbase-entry.type.ts

@@ -14,6 +14,14 @@ interface PocketBaseBaseEntry {
    * Name of the collection the entry belongs to.
    */
   collectionName: string;
+  /**
+   * Date the entry was created.
+   */
+  created?: string | undefined;
+  /**
+   * Date the entry was last updated.
+   */
+  updated?: string | undefined;
 }
 
 /**

package/src/types/pocketbase-loader-options.type.ts

@@ -13,39 +13,38 @@ export interface PocketBaseLoaderOptions {
    */
   collectionName: string;
   /**
-   * Name of the field(s) containing the content of an entry.
-   * This must be the name of a field in the PocketBase collection that contains the content.
+   * Field that should be used as the unique identifier for the collection.
+   * This must be the name of a field in the collection that contains unique values.
+   * If not provided, the `id` field will be used.
+   * The value of this field will be used in `getEntry` and `getEntries` to load the entry or entries.
+   *
+   * If the field is a string, it will be slugified to be used in the URL.
+   */
+  id?: string;
+  /**
+   * Content of the collection in PocketBase.
+   * This must be the name of a field in the collection that contains the content.
    * The content will be parsed as HTML and rendered to the page.
    *
    * If you want to render multiple fields as main content, you can pass an array of field names.
    * The loader will concatenate the content of all fields in the order they are defined in the array.
    * Each block will be contained in a `<section>` element.
    */
-  contentFields?: string | Array<string>;
+  content?: string | Array<string>;
   /**
-   * Name of the field containing the last update date of an entry.
-   * Ideally, this field should be of type `autodate` and have the value "Update" or "Create/Update".
-   * This field is used to only fetch entries that have been modified since the last build.
+   * Email of an admin to get full access to the PocketBase instance.
+   * Together with `adminPassword` this is required to get automatic type generation and to access all resources even if they are not public.
    */
-  updatedField?: string;
+  adminEmail?: string;
   /**
-   * Credentials of a superuser to get full access to the PocketBase instance.
-   * This is required to get automatic type generation, to access all resources even if they are not public and fetch content of hidden fields.
+   * Password of the admin to get full access to the PocketBase instance.
+   * Together with `adminEmail` this is required to get automatic type generation and to access all resources even if they are not public.
    */
-  superuserCredentials?: {
-    /**
-     * Email of the superuser.
-     */
-    email: string;
-    /**
-     * Password of the superuser.
-     */
-    password: string;
-  };
+  adminPassword?: string;
   /**
    * File path to the local schema file.
    * This file will be used to generate the schema for the collection.
-   * If `superuserCredentials` are provided, this option will be ignored.
+   * If admin credentials are provided (see `adminEmail` and `adminPassword`), this option will be ignored.
    */
   localSchema?: string;
   /**
@@ -56,4 +55,9 @@ export interface PocketBaseLoaderOptions {
    * Note that this will only be used for fields of type `json`.
    */
   jsonSchemas?: Record<string, z.ZodSchema>;
+  /**
+   * By default, the loader will only fetch entries that have been modified since the last fetch.
+   * If you want to fetch all entries, set this to `true`.
+   */
+  forceUpdate?: boolean;
 }

package/src/types/pocketbase-schema.type.ts

@@ -2,11 +2,6 @@
  * Entry for a collections schema in PocketBase.
  */
 export interface PocketBaseSchemaEntry {
-  /**
-   * Flag to indicate if the field is hidden.
-   * Hidden fields are not returned in the API response.
-   */
-  hidden: boolean;
   /**
    * Name of the field.
    */
@@ -20,25 +15,20 @@ export interface PocketBaseSchemaEntry {
    */
   required: boolean;
   /**
-   * Values for a select field.
-   * This is only present if the field type is "select".
-   */
-  values?: Array<string>;
-  /**
-   * Maximum number of values for a select field.
-   * This is only present on "select", "relation", and "file" fields.
-   */
-  maxSelect?: number;
-  /**
-   * Whether the field is filled when the entry is created.
-   * This is only present on "autodate" fields.
-   */
-  onCreate?: boolean;
-  /**
-   * Whether the field is updated when the entry is updated.
-   * This is only present on "autodate" fields.
-   */
-  onUpdate?: boolean;
+   * Options for the field.
+   */
+  options: {
+    /**
+     * Values for a select field.
+     * This is only present if the field type is "select".
+     */
+    values?: Array<string>;
+    /**
+     * Maximum number of values for a select field.
+     * This is only present on "select", "relation", and "file" fields.
+     */
+    maxSelect?: number;
+  };
 }
 
 /**
@@ -52,9 +42,9 @@ export interface PocketBaseCollection {
   /**
    * Type of the collection.
    */
-  type: "base" | "view" | "auth";
+  type: 'base' | 'view' | 'auth';
   /**
    * Schema of the collection.
    */
-  fields: Array<PocketBaseSchemaEntry>;
+  schema: Array<PocketBaseSchemaEntry>;
 }

package/src/utils/{get-superuser-token.ts → get-admin-token.ts}

@@ -1,31 +1,27 @@
 import type { AstroIntegrationLogger } from "astro";
 
 /**
- * This function will get a superuser token from the given PocketBase instance.
+ * This function will get an admin token from the given PocketBase instance.
  *
  * @param url URL of the PocketBase instance
- * @param superuserCredentials Credentials of the superuser
+ * @param email Email of the admin
+ * @param password Password of the admin
  *
- * @returns A superuser token to access all resources of the PocketBase instance.
+ * @returns An admin token to access all resources of the PocketBase instance.
  */
-export async function getSuperuserToken(
+export async function getAdminToken(
   url: string,
-  superuserCredentials: {
-    email: string;
-    password: string;
-  },
+  email: string,
+  password: string,
   logger?: AstroIntegrationLogger
 ): Promise<string | undefined> {
   // Build the URL for the login endpoint
-  const loginUrl = new URL(
-    `api/collections/_superusers/auth-with-password`,
-    url
-  ).href;
+  const loginUrl = new URL(`api/admins/auth-with-password`, url).href;
 
   // Create a new FormData object to send the login data
   const loginData = new FormData();
-  loginData.set("identity", superuserCredentials.email);
-  loginData.set("password", superuserCredentials.password);
+  loginData.set("identity", email);
+  loginData.set("password", password);
 
   // Send the login request to get a token
   const loginRequest = await fetch(loginUrl, {

package/src/utils/get-remote-schema.ts

@@ -1,6 +1,6 @@
 import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
 import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
-import { getSuperuserToken } from "./get-superuser-token";
+import { getAdminToken } from "./get-admin-token";
 
 /**
  * Fetches the schema for the specified collection from the PocketBase instance.
@@ -10,17 +10,18 @@ import { getSuperuserToken } from "./get-superuser-token";
 export async function getRemoteSchema(
   options: PocketBaseLoaderOptions
 ): Promise<PocketBaseCollection | undefined> {
-  if (!options.superuserCredentials) {
+  if (!options.adminEmail || !options.adminPassword) {
     return undefined;
   }
 
-  // Get a superuser token
-  const token = await getSuperuserToken(
+  // Get the admin token
+  const token = await getAdminToken(
     options.url,
-    options.superuserCredentials
+    options.adminEmail,
+    options.adminPassword
   );
 
-  // If the token is invalid try another method
+  // If the token is invalid, return the basic schema
   if (!token) {
     return undefined;
   }
@@ -38,7 +39,7 @@ export async function getRemoteSchema(
     headers: schemaHeaders
   });
 
-  // If the request was not successful, try another method
+  // If the request was not successful, return the basic schema
   if (!schemaRequest.ok) {
     const reason = await schemaRequest.json().then((data) => data.message);
     const errorMessage = `Fetching schema from ${options.collectionName} failed with status code ${schemaRequest.status}.\nReason: ${reason}`;

package/src/utils/parse-entry.ts

@@ -1,41 +1,61 @@
 import type { LoaderContext } from "astro/loaders";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import { slugify } from "./slugify";
 
 /**
  * Parse an entry from PocketBase to match the schema and store it in the store.
  *
  * @param entry Entry to parse.
  * @param context Context of the loader.
+ * @param idField Field to use as id for the entry.
+ *                If not provided, the id of the entry will be used.
  * @param contentFields Field(s) to use as content for the entry.
  *                      If multiple fields are used, they will be concatenated and wrapped in `<section>` elements.
  */
 export async function parseEntry(
   entry: PocketBaseEntry,
-  { generateDigest, parseData, store }: LoaderContext,
-  contentFields: string | Array<string> | undefined,
-  updatedField: string | undefined
+  { generateDigest, parseData, store, logger }: LoaderContext,
+  idField?: string,
+  contentFields?: string | Array<string>
 ): Promise<void> {
+  let id = entry.id;
+  if (idField) {
+    // Get the custom ID of the entry if it exists
+    const customEntryId = entry[idField];
+
+    if (!customEntryId) {
+      logger.warn(
+        `The entry "${id}" does not have a value for field ${idField}. Using the default ID instead.`
+      );
+    } else {
+      id = slugify(`${customEntryId}`);
+    }
+  }
+
+  const oldEntry = store.get(id);
+  if (oldEntry && oldEntry.data.id !== entry.id) {
+    logger.warn(
+      `The entry "${entry.id}" seems to be a duplicate of "${oldEntry.data.id}". Please make sure to use unique IDs in the column "${idField}".`
+    );
+  }
+
   // Parse the data to match the schema
   // This will throw an error if the data does not match the schema
   const data = await parseData({
-    id: entry.id,
+    id,
     data: entry
   });
 
-  // Get the updated date of the entry
-  let updated: string | undefined;
-  if (updatedField) {
-    updated = `${entry[updatedField]}`;
-  }
-
   // Generate a digest for the entry
-  // If no updated date is available, the digest will be generated from the whole entry
-  const digest = generateDigest(updated ?? entry);
+  // Normal collections use the updated date that is always updated when the entry is updated.
+  // If the entry was never updated, the created date can be used as a fallback.
+  // View collections don't necessarily publish the updated date, so the whole entry is used for the digest.
+  const digest = generateDigest(entry.updated ?? entry.created ?? entry);
 
   if (!contentFields) {
     // Store the entry
     store.set({
-      id: entry.id,
+      id,
       data,
       digest
     });
@@ -57,7 +77,7 @@ export async function parseEntry(
 
   // Store the entry
   store.set({
-    id: entry.id,
+    id,
     data,
     digest,
     rendered: {

package/src/utils/parse-schema.ts

@@ -6,19 +6,13 @@ import type {
 
 export function parseSchema(
   collection: PocketBaseCollection,
-  customSchemas: Record<string, z.ZodType> | undefined,
-  hasSuperuserRights: boolean
+  customSchemas: Record<string, z.ZodType> | undefined
 ): Record<string, z.ZodType> {
   // Prepare the schemas fields
   const fields: Record<string, z.ZodType> = {};
 
   // Parse every field in the schema
-  for (const field of collection.fields) {
-    // Skip hidden fields if the user does not have superuser rights
-    if (field.hidden && !hasSuperuserRights) {
-      continue;
-    }
-
+  for (const field of collection.schema) {
     let fieldType;
 
     // Determine the field type and create the corresponding Zod type
@@ -32,12 +26,11 @@ export function parseSchema(
         fieldType = z.coerce.boolean();
         break;
       case "date":
-      case "autodate":
         // Coerce and parse the value as a date
         fieldType = z.coerce.date();
         break;
       case "select":
-        if (!field.values) {
+        if (!field.options.values) {
           throw new Error(
             `Field ${field.name} is of type "select" but has no values defined.`
           );
@@ -45,7 +38,7 @@ export function parseSchema(
 
         // Create an enum for the select values
         // @ts-expect-error - Zod complains because the values are not known at compile time and thus the array is not static.
-        const values = z.enum(field.values);
+        const values = z.enum(field.options.values);
 
         // Parse the field type based on the number of values it can have
         fieldType = parseSingleOrMultipleValues(field, values);
@@ -73,12 +66,8 @@ export function parseSchema(
         break;
     }
 
-    // Check if the field is required (onCreate autodate fields are always set)
-    const isRequired =
-      field.required || (field.type === "autodate" && field.onCreate);
-
     // If the field is not required, mark it as optional
-    if (!isRequired) {
+    if (!field.required) {
       fieldType = z.preprocess(
         (val) => val || undefined,
         z.optional(fieldType)
@@ -105,7 +94,7 @@ function parseSingleOrMultipleValues(
   type: z.ZodType
 ) {
   // If the select allows multiple values, create an array of the enum
-  if (field.maxSelect === undefined || field.maxSelect === 1) {
+  if (field.options.maxSelect === undefined || field.options.maxSelect === 1) {
     return type;
   } else {
     return z.array(type);

package/src/utils/slugify.ts

@@ -0,0 +1,22 @@
+/**
+ * Convert a string to a slug.
+ *
+ * Example:
+ * ```ts
+ * slugify("Hello World!"); // hello-world
+ * ```
+ */
+export function slugify(input: string): string {
+  return input
+    .toString()
+    .toLowerCase()
+    .replace(/\s+/g, "-") // Replace spaces with -
+    .replace(/ä/g, "ae") // Replace umlauts
+    .replace(/ö/g, "oe")
+    .replace(/ü/g, "ue")
+    .replace(/ß/g, "ss")
+    .replace(/[^\w-]+/g, "") // Remove all non-word chars
+    .replace(/--+/g, "-") // Replace multiple - with single -
+    .replace(/^-+/, "") // Trim - from start of text
+    .replace(/-+$/, ""); // Trim - from end of text
+}

package/src/utils/transform-files.ts

@@ -17,7 +17,7 @@ export function transformFiles(
   for (const field of fileFields) {
     const fieldName = field.name;
 
-    if (field.maxSelect === 1) {
+    if (field.options.maxSelect === 1) {
       const fileName = entry[fieldName] as string | undefined;
       // Check if a file name is present
       if (!fileName) {