Manual code-splitting

[manuelJung]

Summary

Currently Gatsby only supports dynamic code-splitting (by pages). But there are situations, where this process cannot cleverly decide what is the optimal way to split code. That happens when you have to decide at gatsby's bootstrap phase what components you need. One example is, when you use a CMS that defines a Component as a "renderer":

// exampe of a cms-entry
const content = [
  {
    component: 'MyCoolWidget',
    props: {
      title: "Hello World"
    }
  }
]

// later
import * as React from 'react'
import * as components from './components'

export default function CMS ({content}) {
  return (
    <>
      {content.map(row => {
        const Component = components[row.component]
        return <Component {...row.props} />
      })}
    </>
  )
}

The problem here is, that all possible components gets included into the bundle even if they are not used. The Gatsby code-splitting process cannot decide which components are used and which not (Yes, thats a very specific example but there are many more that basically have to deal with the same problem; I used this example because it's easy to understand). That's not a problem, when you have a static file-structure. But as soon as you have to decide at runtime (or at bootstrap-phase in a gatsby context) which components you want to use you have a problem. Code-Splitting does not work any longer

There are solutions to this: react-loadable and loadable-components are designed exactly for this problem. But: they do not work properly with gatsby. So I think it's time for a more gatsby-ish solution for this problem. We could use the exact same mechanism that we use for page-based code-splitting:

Basic example

// gatsby-node.js

exports.createPages = async ({actions}) => {
  actions.createPage({
    path: '/my-cms-component',
    component: path.resolve(__dirname, 'src/theme/templates/cms.js'),
    context: {cmsIdentifier: 'abc'},
    widgets: {
      MyCoolWidget: path.resolve(__dirname, 'src/theme/widgets/MyCoolWidget.js'),
    }
  })
}

// src/theme/templates/cms.js

import * as React from 'react'
import { graphql } from "gatsby"

export default function CMS ({data, widgets}) {
  return (
    <>
      {data.cms.content.map(row => {
        const Component = widgets[row.component]
        return <Component {...row.props} />
      })}
    </>
  )
}

export const query = graphql`
  query($cmsIdentifier: String!) {
    cms (cmsIdentifier: {eq: $cmsIdentifier}){
      content
    }
  }
`

In the above example I add a property "widgets" to the createPage action. Then gatsby resolves these widgets the same way as the components gets resolved and injects these Widgets as props to the page. That way no unnecessary code can be loaded and you get all the cool stuff that gatsby gives you be default, like prefetching and code-splitting (at a widget-level). Some coole side-effect of this approach is, that page-queries could technically also be used inside widgets.

I already created this feature in a fork of mine and it works really smoothly. It took only 2 hours to implement since the whole data-pipeline already exists. I just had to process the widgets the same way the page.component gets processed.

So my question is: Is this something gatsby wants to support? I do not think this feature is something a little blog needs, but for big projects this can be a really badass feature (we pushed our performance from 75 lighthouse points to 93). If so, what do you think about the above implementation? Should I change something before I make a pull-request?

Motivation

My company has really big webshop with over 1000 cms pages and over 400 000 products. I created a similar setup like gatsby (static rendering...) but now we want to move to gatsby because of the better community. We are really happy with gatsby but the above problem is really annoying. By implementing this feature we were able to precisely split our components for our needs and pushed our lighthouse performance by nearly 20 points.

This problem was originally discussed in #5995 and event @KyleAMathews said that this is something gatsby plans to support. By then nothing happens so here I come with a suggestion for an implementation

[pieh]

This is awesome!

In the above example I add a property "widgets" to the createPage action. Then gatsby resolves these widgets the same way as the components gets resolved and injects these Widgets as props to the page. That way no unnecessary code can be loaded and you get all the cool stuff that gatsby gives you be default, like prefetching and code-splitting (at a widget-level). Some coole side-effect of this approach is, that page-queries could technically also be used inside widgets.

Ok, so this to me is problematic part, because you would need to know what "widgets" are needed to render the page in createPages gatsby node hook. With your setup (content.component stating what component is needed) this is probably not a deal breaker, but in general in createPages we should query only minimal amount of information to create a page (so pick page template, and pass minimal amount of context required to query detailed data later in page query).

I think that the data pipeline part is on point, and we need a way for our loader to load additional resources for a page that will work in SSR properly. Just the part that determines what those resources are is something that needs more thought.

My idea here is to implement this inside data layer. When you query:

query($cmsIdentifier: String!) {
    cms (cmsIdentifier: {eq: $cmsIdentifier}){
      content
    }
  }

the content resolver could look into component field, map them to component file, and add this component file as "dependency" for given page. Ideally this would mean that you would get component in query result. There's a lot of question about details of this and how would user specify mappings etc. Also not sure how feasible implementing something like this is? But this is discussion worth having before jumping in on implementing public API that we would have to stick with for a long time.

We also should think about other cases that something like this might be useful other than just this use case. I was thinking about few examples:

• MDX faces similar challenge with putting too much components in main bundle, and in case of MDX it would be pretty difficult to know those components (with your widget API idea) in createPages.
• We could use same additional loading to fetch critical (above the fold) images before doing page transition

So my question is: Is this something gatsby wants to support? I do not think this feature is something a little blog needs, but for big projects this can be a really badass feature (we pushed our performance from 75 lighthouse points to 93). If so, what do you think about the above implementation? Should I change something before I make a pull-request?

Yes, we do want to support use cases like this, but we also need to be smart about how we implement this. So there will be a lot of discussion here. It would also be beneficial to create RFC after initial discussion here, to make it a more formal proposal.

[universse]

This reminds me of the F8 2019: Building the New Facebook.com with React, GraphQL and Relay @22:00 talk. Not sure how much of it is relevant to Gatsby.

[manuelJung]

@pieh You are right. The createPages hook should be as clean and small as possible. But somewhere you have to calculate your needed widgets. So I ended up to create a custom field extension to calculate my widgets:

// gatsby-node.js

exports.createSchemaCustomization = ({actions}) => {
  ...
  // generates dict for used widgets -> { WidgetA: 'path/to/WidggetA' } 
  createFieldExtension({
    name: 'StoryComponentPaths',
    extend: () => ({
      resolve: async (source, args, context, info) => {
        if(!source.story) return null
        return source.story.components
          .reduce((p,{name}) => {
            p[name] = path.resolve(__dirname, `src/storybook/components/${name}.js`)
            return p
          }, {})
      }
    })
  })
  ...
  createTypes(`
    type Page implements Node {
      ...
      storyComponentPaths: JSON @StoryComponentPaths
    }
  `)
} 

exports.createPages = async ({actions, grapqhl}) => {
  const gq = await graphql(`{
    pages:allPage {
      nodes {
        urlKey
        storyComponentPaths
      }
    }
  }`)

  gq.data.pages.nodes.forEach(page => {
    actions.createPage({
      path: `/page/${page.urlKey}/`,
      component: path.resolve(__dirname, 'src/theme/templates/Page.js'),
      context: {urlKey: page.urlKey},
      widgets: page.storyComponentPaths
    })
  })
}

I think something similar should work with MDX too. You could create a custom field extension that does some static analysis in the mdx content. there you could read all your dependencies and format them in a way you need. That ways your createPages will be clean and small

I think that the data pipeline part is on point, and we need a way for our loader to load additional resources for a page that will work in SSR properly. Just the part that determines what those resources are is something that needs more thought.

I already created this feature in my fork of gatsby. The features are:

• new widgets key in actions.createPage
• creating custom webpack-chunk-names for each prefix: widget-src-widgets-widgeta-js-[hash].js
• adding these chunk names to public/chunk-map.json and to the page-data.json of each route
• preloading widgets on hover (when the page-data.json is prefetched)
• create preload links and regular links in initial static html (for ssr)

Basically the exact same process that a page-component has. If I'm missing something feel free to point it out. The only thing i'm not really familiar with is the aggressive code-splitting process. Maybe here someone would help, that deeply knows this process

[pieh]

@universse Yup, not gonna lie - I was inspired by that and wanted to do something like this ever since I saw that talk :)

@manuelJung
My idea was that you wouldn't have to define widgets in createPage at all.

I will be doing some pseudocode examples do illustrate what I had in mind:

In your gatsby-node -> createPages you would continue to only care about minimal data required to be able to query things for a page so:

exports.createPages = async ({actions, grapqhl}) => {
  const gq = await graphql(`{
    pages:allPage {
      nodes {
        urlKey
-       storyComponentPaths
      }
    }
  }`)

  gq.data.pages.nodes.forEach(page => {
    actions.createPage({
      path: `/page/${page.urlKey}/`,
      component: path.resolve(__dirname, 'src/theme/templates/Page.js'),
      context: {urlKey: page.urlKey},
-     widgets: page.storyComponentPaths
    })
  })
}

The "magic" would happen when executing page queries.

Consider this content data:

[
  {
    "component": "MyCoolWidget",
    "props": {
      "title": "Hello World"
    }
  }
]

Let's assume graphql type name would be CMSBlock for entries in the content array.

exports.createSchemaCustomization = ({actions, schema}) => {
  // create mapping of string component identifier to some concrete component implementation in the project:
  someNewAPIThatRegistersGraphQLComponent('MyCoolWidget', require.resolve(`./src/storybook/components/MyCoolWidget`))

  createTypes(`
    type CMSBlock {
      props: JSON
      component: String @GraphQLComponent
      # this is interesting part, using this yet to be implemented directive, gatsby during query execution would add dependency on components for exact pages where they are used on and on the browser side of things we would automatically convert string to actual react component
    }
  `)
}

So in the page template user could do:

export default ({ data }) => {
  return <div>
    {data.page.content.map(({ Component, props }) => {
        // using Component that came as "query result" directly as component
        return <Component {...props} />
      }
    }
  </div>
}

export const q = graphql`
  query pageQuery($urlKey: String!) {
     page(urlKey: { eq: $urlKey }) {
       content {
         Component: component
         props
       }
     }
  }
`

What @GraphQLComponent extension would do is:

• add component identifier as dependencies for page that executed the query
• instruct loader to convert component identifier into component implementation

With this everything would be lazy, you don't need to know what components will be used for page during createPages. This is definitely trickier to implement, but I feel like is much nicer API to use.

This also align nicer with MDX use case better, because we wouldn't need to do extra static analisys to figure out components/widgets during createPages.

What are your thoughts?

[manuelJung]

ok, i understand. That's a really cool api! but how would you solve ssr, like creating preload links and injecting the used scripts into the DOM. All of this is done within the createPage hook. Also the code-splitting could be a tricky thing: Webpack analyses the code and creates shared chunks (1.[hash].js...) different pages can use. This can be done, because you have a single entry (createPage) for your code-splitting. But as soon as you add another totally different entry (createSchemaCustomization) it can be a really hard task (maybe impossible) to create shared chunks.
But basically I'm with you. Enabling to dynamically load components from within graphql would be a game changer and could lead to really cool new patterns. But to implement this idea can take months or even longer to have a stable api. The "widgets api" could be done within hours since everything is already here.

Can we support both? Also you could basically do the same thing in both apis, both have their strength and weaknesses. Your idea would be perfect for plugins but can be quite complex for beginners, whereas my idea is easy to use, but not so plugin-friendly as yours. Let the programmer decide, what fits best for his needs

[pieh]

ok, i understand. That's a really cool api! but how would you solve ssr, like creating preload links and injecting the used scripts into the DOM.

Under the hood it would be pretty similar to what you already implemented - so page-data for pages would contain list of additional modules (components in this case) that both loader.js (in browser) and static-entry.js (for ssr) would need to handle.

Also the code-splitting could be a tricky thing: Webpack analyses the code and creates shared chunks (1.[hash].js...) different pages can use. This can be done, because you have a single entry (createPage) for your code-splitting. But as soon as you add another totally different entry (createSchemaCustomization) it can be a really hard task (maybe impossible) to create shared chunks.

I don't think there would be any difference in terms of webpack setup for both of our ideas - in the end we would end up with list of additional components that each page depend on and need to figure out what's best strategy for webpack setup for this - should we let webpack do some automatic splitting with splitChunks, should we force separate chunks for each component? Those questions are common for both approaches.

But to implement this idea can take months or even longer to have a stable api. The "widgets api" could be done within hours since everything is already here.

I would argue that implementation part wouldn't take that long (similar to implementation of widgets that you did). But I'm with you about figuring out stable API (and this includes both approaches). Your implementation does add new public APIs and adding those is not something that should be rushed to quickly solve particular use case. This is why I mentioned RFC process, because API design should be scrutinized by a lot of people, especially ones like these that could impact a lot of DX flows (which could impact future API decisions).

Can we support both? Also you could basically do the same thing in both apis, both have their strength and weaknesses. Your idea would be perfect for plugins but can be quite complex for beginners, whereas my idea is easy to use, but not so plugin-friendly as yours. Let the programmer decide, what fits best for his needs

In my idea we would essentially need internal APIs that would accomplish similar things as widgets field in page objects. I could see implementation roadmap for this feature that would first implement those APIs, that you could probably utilize in user code, before full graphql component idea is implemented:

exports.createPages = ({ actions }) => {
  actions.createPage({
    path: `/x`,
    component: <page-template-path>
  })

  // make use of internal api - beware that this can stop working without notice
  actions.internal.addModuleToPageDependencies({
    path: `/x`,
    module: <path-to-component>,
    identifier: `MyCoolWidget`,
  })
}

[manuelJung]

ok. so what are the next steps? Who should create the RFC?

[KyleAMathews]

Awesome to see this discussion! There's a lot of fun things we could do with this. One note is that the API would need to be generic so multiple types of resources could be attached to pages for prefetching (didn't see if that came out clearly in the above discussion).

See my RFC on prefetching critical images for another use case this would satisfy https://github.com/gatsbyjs/rfcs/blob/prefetch-images/text/0000-support-prefetching-images.md

[universse]

Another use case could be loading language bundles. Right now if we query language bundle via page queries, routes of the same language will have their own and potentially duplicated language data passed as props. It would be great if all routes of the same language can share the same bundle.

[manuelJung]

so should I create an RFC or should someone from the gatsby team do this? (due to the complexity)

[pieh]

Just commenting that I didn't forgot about this. We are looking into other cases where this feature/API could be used:

• Using this to tie MDX imports to pages instead of main app bundle (https://www.gatsbyjs.org/packages/gatsby-plugin-mdx/#imports)
• Using this for critical images loading ( Add RFC for adding support for prefetching critical images rfcs#35 )
• Using this to move static query result out of webpack bundles
• Case that @universse mentioned - how this could be used to avoid some semi-global data from either being duplicated in data for all pages or ending up as true global (overfetching)

We need this to figure our requirements and constraints. We need to figure out how those extra resources would be accessed (adding it to page component props won't work ultimately, because at least some of them might end up above page level - so I'm looking into some solution with react context, with Provider wrapping entire application)

so should I create an RFC or should someone from the gatsby team do this? (due to the complexity)

Because of the above, I think I'll be person that will write up RFC for it.

I do think that querying component directly idea will not be part of the rfc (it could be build using that API probably, but this will be out of scope of the initial one)

[gatsbot]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[github-actions]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.
Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community! 💪💜