Appwrite CDN for Astro

Official Appwrite CDN cache adapter for Astro 🚀

This package brings route caching to Astro sites hosted on Appwrite. Cache hits are served by the Appwrite CDN, so the site's function is never invoked for them.

Installation

npm install @appwrite.io/cdn-for-astro

Appwrite Sites runs Astro through @astrojs/node, which stays the adapter. This package supplies the cache provider next to it:

// astro.config.mjs
import { cacheAppwrite } from '@appwrite.io/cdn-for-astro';
import node from '@astrojs/node';
import { defineConfig } from 'astro/config';

export default defineConfig({
  adapter: node({ mode: 'standalone' }),
  cache: {
    provider: cacheAppwrite(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },
});

Astro.cache.set(), routeRules and cache.invalidate() then behave as documented. Cache directives are sent as Appwrite-CDN-Cache-Control and cache tags as Appwrite-CDN-Cache-Key; the Appwrite edge rewrites both into whatever the CDN in front of the domain speaks, and cache.invalidate() purges by cache key or by path through the Appwrite API.

For cache.invalidate() to be allowed to purge, the site's dynamic API key needs the proxy.invalidations.write scope (Appwrite console → your site → Settings → Scopes). Caching itself works without it.

A runnable site covering all of this lives in examples/basic.

Requirements

• Astro ^7.0.0
• Node.js >=22.12.0, which is what Astro 7 itself requires

Options

Every option is optional; the defaults suit a site deployed on Appwrite Sites.

| Option | Default | Description | | ----------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | domain | the domain of the request being served | Domain(s) purged by cache.invalidate(). A purge only clears the domain it names, so a site on several domains has to list them. | | endpoint | APPWRITE_FUNCTION_API_ENDPOINT, then APPWRITE_SITE_API_ENDPOINT | Appwrite API endpoint. Required, so pass it when neither variable is set. | | projectId | APPWRITE_FUNCTION_PROJECT_ID, then APPWRITE_SITE_PROJECT_ID | Appwrite project ID. | | apiKey | the x-appwrite-key request header, then APPWRITE_API_KEY | Key used to invalidate. Prefer the default: a value set here is baked into the build output. | | noStore | true | Send no-store for responses that declare no cache intent, so the CDN's default TTL cannot cache a route that never asked for it. |

Exports

import { cacheAppwrite, AppwriteCacheError } from '@appwrite.io/cdn-for-astro';
import { cacheAppwrite } from '@appwrite.io/cdn-for-astro/cache'; // same thing

AppwriteCacheError is what cache.invalidate() throws when it cannot work out which domain, endpoint, project or key to purge with. Catch it to tell a misconfiguration apart from a failed API call:

try {
  await cache.invalidate({ tags: ['products'] });
} catch (error) {
  if (error instanceof AppwriteCacheError) {
    // Nothing was sent: the provider could not resolve what to purge.
  }
  throw error;
}

Good to know

• Cache keys are normalized. The edge splits Appwrite-CDN-Cache-Key on whitespace and re-joins the keys with commas for the CDN's Cache-Tag, so a tag containing whitespace, a comma or a non-ASCII character is percent-encoded — identically on the response and on the purge. A tag longer than 128 characters once encoded cannot be named by a purge, so it is dropped with a warning; the response is still cached.
• A purge is one API call per reference per domain, and invalidations are rate limited to 60 per minute.
• A path purge clears the exact path, not copies cached under the same path with a query string. Tag those and purge by tag instead.
• To purge a whole domain, call createInvalidation({ domain, type: 'all' }) directly — Astro's invalidate() has no equivalent.
• Caching is a no-op in astro dev. Astro disables it in dev, so inspect headers against a build.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for the development setup, and SECURITY.md for reporting a vulnerability.

Support

• Join the Appwrite Discord for help with Appwrite Sites and the CDN.
• Read the Appwrite documentation and the Astro caching guide.
• Submit bug reports and feature requests as GitHub issues.

License

MIT — see LICENSE.