Dynamic Routes and Data Fetching

dustinlacewell commented 3 years ago

🚀 Feature

Support "nextjs-like" dynamic routes so that N pages may be generated from pages with templated filenames ([thingid].tsx).

Have you read the Contributing Guidelines on issues?

yes

Motivation

Project I'm working on has a bunch of static json data from which we'd like to seed multiple pages. People on the project are super torn because Docusaurus offers so much ease and flexibility for everything we need, but skeptical of doing pre-build generation ourselves via a plugin, etc.

Pitch

Support Dynamic Routes and Data Fetching ala NextJS:

In NextJS, you just make a file with a templated filename, slap a getStaticProps and getStaticPaths functions in the module and you're good to go. If Docusaurus had this feature, when you would ever need to actually reach for NextJS?! :)

slorber commented 3 years ago

My goal is to make page creation much simpler than it is currently so that you can easily create page with custom props easily from a node script.

But I don't think the API will look like the Next one at first, as it requires significant investment to strip the node code from browser code in pages with Babel.

The first version is likely to look more like gatsby-node createPage(), as it's closer to what we already have

If we can build a convenient API like nexjts with better collocation, why not but it will likely come later

Le sam. 1 mai 2021 à 10:35, Dustin Lacewell @.***> a écrit :

🚀 Feature

Support "nextjs-like" dynamic routes so that N pages may be generated from pages with templated filenames ([thingid].tsx). Have you read the Contributing Guidelines on issues https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md#reporting-new-issues ?

yes Motivation

Project I'm working on has a bunch of static json data from which we'd like to seed multiple pages. People on the project are super torn because Docusaurus offers so much ease and flexibility for everything we need, but skeptical of doing pre-build generation ourselves via a plugin, etc. Pitch

Support Dynamic Routes and Data Fetching ala NextJS:

https://nextjs.org/docs/basic-features/data-fetching

https://nextjs.org/docs/routing/dynamic-routes

In NextJS, you just make a file with a templated filename, slap a getStaticProps and getStaticPaths functions in the module and you're good to go. If Docusaurus had this feature, when you would ever need to actually reach for NextJS?! :)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/facebook/docusaurus/issues/4710, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAFW6PTCKJ5L53PTZNXQTRLTLO4LJANCNFSM436DFKHA .

dustinlacewell commented 3 years ago

Are you saying that, as a "node script", this would be a pre-build generation step?

slorber commented 3 years ago

It would be a plugin like other plugins.

You would write something like

const siteConfig = {
  sitePlugin: {

    // Get data from anywhere
    loadContent: async () => {
      return {
        staticPaths: await getMyStaticPathsWithProps()
      };
    },

    // Create static routes
    contentLoaded: async ({ content, actions }) => {
      content.staticPaths.forEach(staticPath => {
        actions.createPage({
          component: "@site/src/components/ProductPage.js",
          path: staticPath.path,
          props: staticPath.props
        });
      });
    }
  }
};

Eventually, we could offer a more straightforward API, but basically you can already build something quite similar today, it's just we don't have a actions.createPage yet, only a actions.createRoute with a less convenient API

1mamute commented 3 years ago

I mentioned this issue in the following documentation issue I've opened as I'm having trouble with the same thing: https://github.com/facebook/docusaurus/issues/5015

Next.js is another very popular hybrid React framework. It can help you build a good documentation website, but it is not opinionated toward the documentation use-case, and it will require a lot more work to implement what Docusaurus provides out-of-the-box.

@slorber can you elaborate on that if possible?

I found Docusaurus while searching for a documentation solution in React, some of them aren't updated or isn't maintained anymore and Docusaurus is great!

Yet learning to build a Docusaurus documentation/blog to me is feeling like learning a whole new React framework. There are custom hooks, plugins, themes, presets, babel configurations, webpack configurations. Why??? Is Docusaurus a React Framework? Is it a library? a template?

I can't help but have a strong feeling that Docusaurus heavily reinvented the wheel here. If I do so choose to keep learning Docusaurus, i think i'll just have to update my resumé putting Docusaurus in the javascript frameworks category.

This is a open-hearted question from someone with only a year or so of experience in react development (not a pro by any means) just genuinely interested to know: how much more difficult is to implement Docusaurus features in a active-developed, highly extensible, battle-tested, static-site-generator react framework like CRA, Next.js or Gatsby? Did Facebook wanted to stay vendor neutral?

Couldn't Docusaurus have been a NPM package bundled with create-docusaurus-app npx templates?

slorber commented 3 years ago

Yet learning to build a Docusaurus documentation/blog to me is feeling like learning a whole new React framework. There are custom hooks, plugins, themes, presets, babel configurations, webpack configurations.

Yes, this is because it is actually a new React framework. If you use Next.js, you learn Next.js, if you use Docusaurus you also learn Docusaurus.

I can't help but have a strong feeling that Docusaurus heavily reinvented the wheel here. If I do so choose to keep learning Docusaurus, i think i'll just have to update my resumé putting Docusaurus in the javascript frameworks category.

This is a open-hearted question from someone with only a year or so of experience in react development (not a pro by any means) just genuinely interested to know: how much more difficult is to implement Docusaurus features in a active-developed, highly extensible, battle-tested, static-site-generator react framework like CRA, Next.js or Gatsby? Did Facebook wanted to stay vendor neutral?

This has been discussed multiple times internally and we decided to not be based on top of another SSG and build our own SSG to have stronger opinions. It has for sure pros and cons. One of the pros is that we have full control over our own stack, and can do the changes when we want/need to without waiting for an upstream dependency to make what we want to do possible. If Next.js decides to implement something we don't agree with, or refuse to implement an API we absolutely need, can we do anything about it?

That being said, I guess we could revisit this question for Docusaurus v3 and see if an existing React framework can be a good fit to host it, but it's unlikely we'd be able to migrate everything seamlessly.

Remember you use Docusaurus first for the simplicity of deploying a good doc site. You don't have to understand all of it, and most users are happy without knowing anything about plugins and lifecycles. If you want to build the e-commerce site for Apple.com, obviously you should use Next.js and not Docusaurus.

We are also a small team compared to Vercel/Gatsby: we are mainly good on one specific use case, but it's hard to compete in a general way

You can also take a look at Nextra or Dokz if you are looking for a doc solution built on top of Next. These are less featured than Docusaurus but will allow you to more easily integrate with a CMS the way you are used to.

1mamute commented 3 years ago

@slorber I completely understand the project visions right now. Thank you for clarifying everything for us.

One of the pros is that we have full control over our own stack, and can do the changes when we want/need to without waiting for an upstream dependency to make what we want to do possible. If Next.js decides to implement something we don't agree with, or refuse to implement an API we absolutely need, can we do anything about it?

That's absolutely reasonable, don't sound like a good move to depend on third parties to implement things that are high priority for Docusaurus. On the other hand, choosing a framework that had most things Docusaurus needed and then implement our own APIs on top of that would make a reasonable decision as well, but I imagine that this was discussed internally several times already and the path the team chose seems to be working really well for the project anyway, congrats!

Don't know if sounded rude but that was absolutely not my intention, i'm just curious about the project and this issue seemed like a good place to raise this discussion.

slorber commented 1 week ago

Note: although we still don't have a way to generate static pages for dynamic routes, it's still possible to use dynamic client-side routes in Docusaurus.

I wrote a detailed explanation here: https://github.com/facebook/docusaurus/issues/10564#issuecomment-2399308347

facebook / docusaurus