SPA opt-out: make prefetching/preloading and routing configurable about docusaurus

[pkowaluk]

This is great, Sébastien, thanks for sharing this detailed recipe. We will go that route for sure. You are right that preserving the SPA functionality makes for a better user experience. Feel free to close this feature request.

…

On Fri, Mar 29, 2024, 10:19 Sébastien Lorber ***@***.***> wrote: Building 2 sites will give a better experience in this case IMHO, because it would be secure and you would keep the SPA behavior, which is important not only to improve the navigation experience but also to preserve the state when navigating. For example, if you navigate through regular links, the docs sidebar items collapsed state would reset. I would do something like: VARIANT=public docusaurus build --out-dir build/public VARIANT=private docusaurus build --out-dir build/private Based on env variables you could use include / exclude params in the docs plugin to choose which docs to include. Then I would use a Vercel Edge auth middleware. You'd have to figure out the details but here are some refs and examples: - https://vercel.com/docs/functions/edge-middleware/middleware-api <https://vercel.com/docs/functions/edge-middleware/middleware-api> - https://github.com/vercel/examples/tree/main/edge-middleware <https://github.com/vercel/examples/tree/main/edge-middleware> I guess something like this could work: import { rewrite } from ***@***.***/edge'; export default function middleware(request: Request) { const url = new URL(request.url); if (isAuthenticated(req)) { url.pathname = "/private" + url.pathname; } else { url.pathname = "/public" + url.pathname; } return rewrite(url);} Now it's your responsibility to implement the isAuthenticated() method. Note: you shouldn't use baseUrl: '/public/' and baseUrl: '/private/' when building because, even though the files will be deployed under a subpath, you'd still serve them from the root without any prefix. Now if you want you can also keep the prefix in the URL and use a redirect instead of a rewrite. And you are not forced to use subpaths either. Using subdomains like private.myDoc.com and public.myDoc.com or whatever else you want can also work with both subpath and subdomains strategies. — Reply to this email directly, view it on GitHub <#9990 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALZ3E7JFNBJCAV3NO7QY7RLY2UPX3AVCNFSM6AAAAABFLFF6GCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRWHEZDSMBYGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[slorber]

HI.

I understand that you want to drive the discussion to a concrete technical solution, but to me, it is more important that you explain the business use case, and the outcome you want from all this. This way, I can figure out the technical solution, and maybe propose you an alternative/workaround.

Can you explain:

• why you want to protect a single URL in the first place?
• why did you choose Docusaurus given that constraint?
• why you want to link to it from a public page, and what should be the experience for a user when they click on the link considering they are not authenticated?

---

What you need looks complicated to implement and is not really an initial goal of Docusaurus. I doubt we'll make this kind of use case a priority because the ROI would be quite low considering only you ask for something like this so far.

Even if we disable the SPA navigation, prefetching and everything, the secret page bundles remain emitted, are available publicly through an URL /assets/js/bundleX.js that hackers can guess with brute force. One solution could

A possible solution could be to colocate the page JS bundle near close the HTML file. This way even if the JS bundle is referenced in a map, it can't be downloaded if you protect the /docs/top-secret/birthday-party-plans path. It is probably possible to use configureWebpack plugin lifecycle today to achieve that.

---

Note that we also have a goal make Docusaurus work without any JS. We are far from done yet but HTML/CSS is improving, and if JS can be considered as a progressive enhancement, we could simply bypass React hydration, use regular links, and only emit HTML/CSS files. Track #3030

Hydrating React and disabling the SPA soft-navigation for all links just because you have one or a few secret routes doesn't really seem like a good idea to me overall. This degrades the whole user experience for users who only browse public pages, is not so easy to implement and this feature probably has very low traction among our users.

[pkowaluk]

Thanks for taking on the discussion. - why you want to protect a single URL in the first place? We want to decide on a page-by-page basis. About half the pages will need to be public, and the rest password-protected. - why did you choose Docusaurus given that constraint? It's a new requirement. We've been using Docusaurus for a while and our approach so far was that we decided about access on a site level - either the entire Docusaurus site is public or not. Now we want to have more fine-grained control. We could switch to a different SSG, but that would be a significant investment, so we're trying to figure out if we can stay with Docusaurus and still accomplish our goals - why you want to link to it from a public page, and what should be the experience for a user when they click on the link considering they are not authenticated? Given that some pages are public and some are not, we want to maintain the current punks. If a user clicks a link the don't have access to, our server can handle it - redirect them to a login page. I understand that this is not a core use case for you guys, and we'd be willing to contribute this feature ourselves. Of course, given your guidance and following all your rules. For example, that idea about collocated bundles is a great suggestion. Let me know if I can do anything to help move this forward. At the same time I understand you have different priorities and I understand if you don't want to support us in this. Docusaurus remains an awesome SSG and a real gem for the open source community.

…

On Thu, Mar 28, 2024, 11:08 Sébastien Lorber ***@***.***> wrote: HI. I understand that you want to drive the discussion to a concrete technical solution, but to me, it is more important that you explain the business use case, and the outcome you want from all this. This way, I can figure out the technical solution, and maybe propose you an alternative/workaround. Can you explain: - why you want to protect a single URL in the first place? - why did you choose Docusaurus given that constraint? - why you want to link to it from a public page, and what should be the experience for a user when they click on the link considering they are not authenticated? ------------------------------ What you need looks complicated to implement and is not really an initial goal of Docusaurus. I doubt we'll make this kind of use case a priority because the ROI would be quite low considering only you ask for something like this so far. Even if we disable the SPA navigation, prefetching and everything, the secret page bundles remain emitted, are available publicly through an URL /assets/js/bundleX.js that hackers can guess with brute force. One solution could A possible solution could be to colocate the page JS bundle near close the HTML file. This way even if the JS bundle is referenced in a map, it can't be downloaded if you protect the /docs/top-secret/birthday-party-plans path. It is probably possible to use configureWebpack plugin lifecycle today to achieve that. — Reply to this email directly, view it on GitHub <#9990 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALZ3E7JFIQ5MHQSNIQLPLQDY2PMYNAVCNFSM6AAAAABFLFF6GCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRUHAZTCNRXGY> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[slorber]

Thanks

So you want only some pages to be "protected".

Are all the logged-in users of your site able to access the exact same pages, or each user can see a different set of protected pages?

[pkowaluk]

Yes, only some pages are to be protected. We're experimenting with adding a custom prop in the prolog called `public` which can be set to either `true` or `false` and some way to set a default. Now, we also have a prop called `internal` which makes pages available only to employees, so not all users are meant to see the same pages. This prop is tricky because we've implemented it in the front end and we didn't really care about the contents being secure. We could leave it as is, but maybe there's a way to set it up so that it's similarly protected. 🤔

…

On Thu, Mar 28, 2024, 12:38 Sébastien Lorber ***@***.***> wrote: Thanks So you want only some pages to be "protected". Are all the logged-in users of your site able to access the exact same pages, or each user can see a different set of protected pages? — Reply to this email directly, view it on GitHub <#9990 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALZ3E7MYL2KJAMQHLJQ6AQ3Y2PXKTAVCNFSM6AAAAABFLFF6GCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRUHE3TMMRSGA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[slorber]

I'm not sure to understand sorry 😅

If logged in users see the exact same content, you could build the same site in 2 variants, one public, one authenticated. Then deploy both to a CDN and use a Middleware proxy to serve one site or the author depending on auth status. For example, try Vercel + edge Middleware or Cloudflare + Worker.

[pkowaluk]

Good suggestion, Sebastien. That's our plan B if we cannot find a way to make "one site" work. So, are you saying we should not move forward with the feature and build two sites instead?

…

On Thu, Mar 28, 2024, 21:33 Sébastien Lorber ***@***.***> wrote: I'm not sure to understand sorry 😅 If logged in users see the exact same content, you could build the same site in 2 variants, one public, one authenticated. Then deploy both to a CDN and use a Middleware proxy to serve one site or the author depending on auth status. For example, try Vercel + edge Middleware or Cloudflare + Worker. — Reply to this email directly, view it on GitHub <#9990 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALZ3E7KWGIXAXSBWPXJOEVDY2RWBNAVCNFSM6AAAAABFLFF6GCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMRWGA3DKNRXGE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[slorber]

Building 2 sites will give a better experience in this case IMHO, because it would be secure and you would keep the SPA behavior, which is important not only to improve the navigation experience but also to preserve the state when navigating. For example, if you navigate through regular links, the docs sidebar items collapsed state would reset.

I would do something like:

VARIANT=public docusaurus build --out-dir build/public
VARIANT=private docusaurus build --out-dir build/private

Based on env variables you could use include / exclude params in the docs plugin to choose which docs to include.

Then I would use a Vercel Edge auth middleware. You'd have to figure out the details but here are some refs and examples:

• https://vercel.com/docs/functions/edge-middleware/middleware-api
• https://github.com/vercel/examples/tree/main/edge-middleware

I guess something like this could work:

import { rewrite } from '@vercel/edge';
 
export default function middleware(request: Request) {
  const url = new URL(request.url);
  if (isAuthenticated(req)) {
    url.pathname = "/private" + url.pathname;
  }
  else {
    url.pathname = "/public" + url.pathname;
  }
  return rewrite(url);
}

Now it's your responsibility to implement the isAuthenticated() method.

Note: you shouldn't use baseUrl: '/public/' and baseUrl: '/private/' when building because, even though the files will be deployed under a subpath, you'd still serve them from the root without any prefix.

Now if you want you can also keep the prefix in the URL and use a redirect instead of a rewrite.
And you are not forced to use subpaths either. Using subdomains like private.myDoc.com and public.myDoc.com or whatever else you want can also work with both subpath and subdomains strategies.