Summary

Provide an option to specify a CDN URL for static assets to serve from in production.

Background & Motivation

Large traffic sites often have CDN servers that are optimized to serve assets only. For example, a site served from https://astro.build would reference all it's assets from https://cdn.astro.build.

A CDN URL would also allow assets from multiple sites to be deployed to the same CDN server to share the performance, where they can be separated by URL subpaths.

There are also prior art from other frameworks that users want in Astro too:

Goals

Provide an option to prepend generated asset links with the CDN URL.
Provide an env variable to access the CDN URL (import.meta.env.*) to prepend links manually.
Works with static and server output.
Works with existing Astro features, like content collections, astro:assets images, and @astrojs/image.

Non-Goals

Auto-prefixing CDN URLs to user-created <link href> or <img src> etc.
Allow changing the CDN URL in runtime.
Handling CDN URLs for files in the public directory.
- Users have to preprend the URL themselves if needed.
The Astro CDN service.

Example

Astro config:

// astro.config.js
export default defineConfig({
  build: {
    cdnUrl: 'https://cdn.example.com'
  }
})

Generated HTML example:

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://cdn.example.com/index.123456.css" />
  </head>
  <body>
    <!-- if astro images are used -->
    <img src="https://cdn.example.com/penguin.png" />
  </body>
 </html>

Details and behaviours:

With the default build.assets option of _astro directory, the user will copy all the files from the dist/_astro directory to the https://cdn.example.com server.
The CDN URL is not affected by base option, because base is the serving base of the user-facing site URL, e.g. https://example.com/foo/. (similar to prior art)
The CDN URL can accept any pathname, for example https://cdn.example.com/project-a, and Astro would include it in the built URL.

More prior art research

Framework	Option	What users have to do	Public files supported?
Nextjs	`assetPrefix`	Upload `.next/static/` as `https://cdn.com/_next/static/`	❌
Nuxt	`app.cdnURL`	Upload `.output/public/_nuxt/` as `https://cdn.com/_nuxt/`	❌
SvelteKit	`path.assets`	Upload `.svelte-kit/output/client/_app/` as `https://cdn.com/_app/`	❌

*Upload path may depend on deployment target / adapter

ZebraFlesh commented 1 year ago

Works with existing Astro features, like content collections and astro:assets images.

Is the intention that this will also work with Astro generated <picture> tags? Currently these come from the <Picture> element in the @astrojs/image integration. However, I'm unclear on how astro:assets relates to <picture> tags since astro:assets are new and experimental.

bluwy commented 1 year ago

Good point. Since astro:assets is still experimental, let's make sure @astro/image would work with this proposal too. <picture> should also work. Will update the issue.

FredKSchott commented 1 year ago

Probably okay to leave as-is given the good convo already kicked off, but for future proposals: we discussed reducing the effort on Stage 1/2 and moving away from including a specific solution in the OP to just including background/goals/non-goals. Solution ideas and discussion can go in a comment below (optional) at anytime, or just the RFC.

Two examples:

matthewp commented 1 year ago

This is released, thank you @bluwy !

withastro / roadmap

CDN support #534