Asset prefix for static files

[garraflavatra]

Is it possible to have an asset prefix in Docusaurus?

For example: having static files (.js, .css, .png etc.) served from https://cdn.example.com, while the docs are available at https://docs.example.com.

This feature is inspired on Gatsby's assetPrefix setting, and is useful when using a service like S3.

Thanks for this great documenting tool!

[slorber]

Thanks

This is currently not possible.

What is your motivation to have this feature exactly?
That seems like a quite niche use-case and may be complicated to implement.

What's the motivation to have HTML files on one domain, and JS files on another?

Note Amazon S3 is not a CDN, only CloudFront is.
Why not deploying everything to S3+Cloudfront? (including HTML files?).

[slorber]

@shyr1punk I know what a CDN is. What I need to know is why you want SOME files on a CDN and some others not on a CDN.

You should put ALL files on the CDN, not just assets. We could allow you to do so, but I don't think it's a good practice nor that it has valid reasons.

Even your Vercel link mentions this.

Attention: Deploying to Vercel automatically configures a global CDN for your Next.js project. You do not need to manually setup an Asset Prefix.

Gatsby also says this:

In some circumstances you may want to deploy assets (non-HTML resources such as JavaScript, CSS, etc.) to a separate domain. Typically this is when you’re required to use a dedicated CDN for assets or need to follow company-specific hosting policies.

If you want our small team to build this, you really have to give us the motivations. There might be motivations for sure, like integrating with weird legacy systems or handling weird corporate deployment policies, but we won't build anything without these motivations being clearly exposed and showing that our effort to build this will bring a decent ROI.

[shyr1punk]

What I need to know is why you want SOME files on a CDN and some others not on a CDN.

You should put ALL files on the CDN, not just assets.

Sorry, I don't understand.

We can't serve HTML files from CDN because HTML files should be served from web server with proper domain name. JS, CSS, Images can be served from CDN (domain name not important). Why we want to use CDN for this files? CDN provides cheap and fast file serving. My corporate website protected from DDoS and company pays for traffic. Moving part of contents to CDN reduces costs and improves performance.

This option available in Next.js by assetsPrefix.

Even your Vercel link mentions this.

Attention: Deploying to Vercel automatically configures a global CDN for your Next.js project. You do not need to manually setup an Asset Prefix.

What mentioned? Vercel !== Next.js. If we build Next.js application, deploy to own servers and want use CDN we need to configure assetsPrefix manually.

[garraflavatra]

We can't serve HTML files from CDN because HTML files should be served from web server with proper domain name.

It is possible to host HTML files using a CDN if you just point your A/AAAA/CNAME to the CDN and configure the CDN to recognise your domain name.

You don’t need nginx or httpd or Caddy (let alone Express or Node.js) or whatever you’re using to host static files, HTML included…

Moving part of contents to CDN reduces costs and improves performance.

So why not everything?

[garraflavatra]

See this https://www.freecodecamp.org/news/cjn-how-to-point-your-domain-to-s3-website-bucket/amp/

[slorber]

We can't serve HTML files from CDN because HTML files should be served from web server with proper domain name.

You can indeed. See for example: we serve docusaurus.io from Netlify CDN and it's a clean domain name. We don't need to use 2 separate domains for this, we put everything behind a clean domain name and do not split between docusaurus.io and cdn.docusaurus.io

If your company cares about perf, they should put everything on the CDN, under a clean domain name (not just assets).

You can have CDN-level DDos protection too, cf Cloudflare.

My point here is that it is not a technical limitation: you can do this technically, and this is actually what most users do and what we recommend. What I want to understand is why you want to diverge, considering it's not a technical limitation.

[garraflavatra]

I've been following following this discussion all the time, more or less.

There is not an exact reason for it, I was just wondering if it is possible.

I didn't take the time to explain as I've been focusing on other things, it wasn't really important enough, but there is a reason.

It is important to share your motivation.
Why it will be better exactly? You have to explain. So far nobody gave any good reason.

The reason I initially asked whether this was possible, hasn’t been mentioned yet: cookies.

Docusaurus as an SSG already outputs nothing but static assets (HTML, CSS, and JS) which you can just deploy to some service like S3 or Azure SWA — there is no need to separate those files from some server-rendered content because there is no server-rendered content — if you do not host those static files on the same domain.

Suppose a company has a heavy web-app that sets 3 kB of cookies¹ at https://company.com/, and a documentation site built by Docusaurus at https://company.com/docs/ which documents the web-app, its API etc. All those sub-sites are hosted under one apex domain (company.com), and not on their own domain.

For the cookies to be sent to the server of the web-app, their path must be set to / since the app is hosted at https://company.com/. The cookies however will also be sent to the documentation CDN since it's hosted at /docs/, which falls under /, the path at which the app is served. This is unnecessary as the cookies are only to be used by the app and not by the documentation site, which means that 3 kB of useless cookie data is sent over the line for each request. For the Docusaurus website, this means an unnecessary transport of at least 126 kB².

That's not really a great deal, but eliminating it increases page speed a bit (at least on slower devices or networks).

Hope this clarifies my question a bit. Congrats on v2 (and 2.2 already)!

Footnotes

1. This is not an unimaginable scenario; go to https://dictionary.com, open devtools and look at cookies. One cookie on itself (eupubconsent-v2) is already 3 kB (see image).

   ↩

2. On https://docusaurus.io/ there are 42 requests made (filtered by HTML, CSS, and JS — no images and XHR requests etc.). 42 requests x 3 kB of cookies on each request = 126 kB. ↩

[slorber]

Thanks for the detailed explanation.

I understand the use-case but it's indeed quite niche and we probably won't build support just for this.

Some possible workarounds:

• Use smaller cookies
• Only apply cookie to a subpath (in case / doesn't need it?)
• Post-process all HTML files yourself, replace "/docs/assets/* by "https://myCdn.com/docs/assets/* and configure your CDN to proxy the main deployment

[garraflavatra]

Thanks for your time, I understand this won’t be implemented as most users don’t need this. The last workaround you mentioned would indeed be a good solution. And being able to serve smaller cookies would be nice too…

[clzczhc]

Now, this requirement can be fulfilled by writing a custom plugin and utilizing configureWebpack to set the publicPath. Additionally, the prefix of CSS and JavaScript in the HTML can be modified through the ssrTemplate option in the docusaurus.config.js. -- to those who have similar needs.