RFC: Vulcan Package Format

[eric-burel]

Idea

Calling registerComponent or addRoute anywhere in the code is magic but we won't be able to track those down during a build step.

Instead, we could expect developer to explicitly export routes and components at the root of every package.

This approach is now recommended in storybook, that moved from the dynamic pattern :

storiesOf("whatever").add("some story", () => (<MyComponent />)

to Component Story Format

export default {
  title: 'Path/To/MyComponent',
  component: MyComponent,
  decorators: [ ... ],
  parameters: { ... }
}
export const someStory = () => (<MyComponent />)

The big difference is that now stories can be understood by a build tool, since they are explicitly exported. Advantages are basically infinite, mostly regarding 3rd party tools interaction.

Apollo Universal Starter Kit is close to this pattern, but still rely on a dynamic approach by exporting a ServerModule object:

import Counter from './sql';

import schema from './schema.graphql';
import createResolvers from './resolvers';
import ServerModule from '@gqlapp/module-server-ts';

export default new ServerModule({
  schema: [schema],
  createResolversFunc: [createResolvers],
  createContextFunc: [() => ({ Counter: new Counter() })]
});

I'd like to go even further and expect the user to simply export an object. Vulcan would take care of generating relevant code.

Next

Eventually, this format should be somehow compatible with Next plugin format: vercel/next.js#9133.

It could be done through a specific field of the export or a specific file in our Vulcan packages, like next.plugin.ts.

Examples

• Material UI is a good example for packages that should affect the frontend/SSR at a low level.
• Vulcan automated backoffice is a good example of page generation
• Vulcan auth is a good example of full-stack feature (auth resolvers, mutations, and UI
• ...to be completed

List of needs

• Wrap the custom "_app" component with new items, eg Material UI Theme
• Add hooks to the custom "_app" component, eg Material UI JSS removal
• Export custom values specific to the package, eg Material UI themes
• Extends the document "getInitialProps" method with Material UI (not easy, because we need to enhance the ctx object, then compute the raw "Document.getInitialProps", then compute Material UI own props, so there is an imbrication)
• Extend the Storybook Webpack configuration
• Extend the app Webpack configuration
• Extend the Cypress Webpack configuration
• Declare the possible settings
• Export graphql fragment, schemas
• ...to be completed progressively