React-styleguidist: Consuming externally compiled files and maintaining their connection to sources

[Guria]

components: {
  parse: './node_modules/my-lib/src/**/*.jsx',
  load: './node_modules/my-lib/dist/**/*.js',
  css: './node_modules/my-lib/dist/**/*.css'
}

It would help to use already builded components for demo purposes and sources to parse with react-docgen

[sapegin]

Not sure I understand what do you need. Could you explain your use case?

[mik01aj]

@Guria I don't understand your example, but you can use require in your examples.md to show some external demo components.

[Guria]

react-docgen doesn't requires component, but parses component source as text. Moreover, it is not being able to parse transpiled builded files. Live examples must be builded to be able to run, on the other side.

Documentation recommends to extend webpack config with appropriate loaders to build components. It's possible, but my suggestion is to be able define path to transpiled components.

In my case I have several libs with both sources and transpiled build in node_modules. I want pass sources to make react-docgen happy and use already built files for demo purposes.

[mik01aj]

I read your comment 3 times and I still don't understand what you're trying to do and what is your problem.

[sapegin]

Looks like it’s out of scope of the Styleguidist.

[Guria]

Using dist build

module.exports = {
  sections: [
    {
      name: 'Layout Components',
      content: './node_modules/some-lib/README.md',
      components: './node_modules/some-lib/dist/*.js'
    }
  ]
}

• ok for styleguidist to use for demo purposes
• but not ok for parsing with react-docgen: Error: No suitable component definition found. for Stateful components transpiled from es6 class definition.

Using sources

module.exports = {
  sections: [
    {
      name: 'Layout Components',
      content: './node_modules/some-lib/README.md',
      components: './node_modules/some-lib/lib/*.jsx'
    }
  ]
}

• ok to parse with react-docgen
• but not ok to direct require for demo purposes.You may need an appropriate loader to handle this file type.

Current solution

var path = require('path')
var merge = require('webpack-merge')

var localConfig = {
  module: {
    loaders: [
      {
        test: /\.jsx?$/,
        include: path.join(__dirname, './node_modules/some-lib/lib/'),
        loader: 'babel'
      }
}

module.exports = {
  sections: [
    {
      name: 'Layout Components',
      content: './node_modules/some-lib/README.md',
      components: './node_modules/some-lib/lib/*.jsx'
    }
  ],
  updateWebpackConfig: function (webpackConfig, env) {
    return merge(webpackConfig, localConfig)
  }
}

• both react-docgen and styleguidist happy
• I have to manage loaders, babel options, transforms, etc for each library

Proposal

module.exports = {
  sections: [
    {
      name: 'Layout Components',
      content: './node_modules/some-lib/README.md',
      components: {
        source: './node_modules/some-lib/lib/*.jsx',
        dist: './node_modules/some-lib/dist/*.js'
      }
    }
  ]
}

[mik01aj]

The "current solution" is what we recommend in the docs.

If you don't want 2 configs, you can use .babelrc for babel (will only work with babel 6) and re-use some parts of your webpack config via require('./webpack.config') and putting them where needed.

[Guria]

I know about recommendation. In my case it will be bunch of libraries. It will be really a mess of require('some-lib/webpack.config') with per library hacks to patch include, exclude pathes, etc.

[mik01aj]

If you need some special Webpack config to use some libraries, then it's a problem with these libraries.

[sapegin]

I’m going to close it because it’s out of the scope of the Styleguidist and you already have a working solution.

[Guria]

It is definitely not a problem of my libraries. Libraries are distributed with compiled build to es5 commonjs. Library consumer doesn't have to know anything about build tools used. And my suggestion was to allow styleguidist to consume built files, while also providing path to sources to make react-docgen able to generate docs for components.

[mik01aj]

Ah, I think that now I finally understand your point.

You want to compile your jsx to js with some tool outside styleguidist (be it webpack, babel or anything), and then you want styleguidist to consume these compiled files instead of compiling them again. Correct?

That's a fair point, and it should be possible to do it by rewriting some paths for webpack. But on the other hand, I'm not sure if people actually do this often in their projects. In the cases I've seen, there is no separation between transpiling and bundling step, and the individual transpiled files are not saved anywhere. So I'm not sure there is a great need for this. What you propose would be cleaner and faster for your project, but I'm not sure it will be that useful for the general public.

[Guria]

compile your jsx to js with some tool outside styleguidist (be it webpack, babel or anything)

Exactly. it already compiled and published to internal npm server

and then you want styleguidist to consume these compiled files instead of compiling them again

Yes. I just install them from local npm and want styleguidist to be able use already compiled one for demo purposes and sources for docgeneration.

But on the other hand, I'm not sure if people actually do this often in their projects.
What you propose would be cleaner and faster for your project, but I'm not sure it will be that useful for the general public.

It expected to be opt-in, so shouldn't affect general public. If you are not ready to spent time for not common case, I understand you. I can do it on my own with your permission and guidence.

[sapegin]

so shouldn't affect general public.

Don’t forget about maintaining this code and docs. Every new feature makes code and docs harder to understand and modify. And every new feature we’d add later should take this one into account in order not to break it.

So if you can make an external library for that it would be great. If you need some hooks and API in Styleguidist for that — we could add it it think.

[Guria]

what about option just like getExampleFilename, but for compiled source?

[sapegin]

Can you show an example? Might work.

[Guria]

module.exports = {
  sections: [
    {
      name: 'Layout Components',
      content: './node_modules/some-lib/README.md',
      components: './node_modules/some-lib/dist/*.js'
    }
  ],
  getComponentSource: function (path) {
    return path.replace('dist', 'lib')
  }
}

[sapegin]

Looks good for me.

[gazpachu]

Hi @Guria did u manage to solve the loading of the components and their examples from an external dependency?

I also don't want to mix styleguidist with my UI components lib. Thanks!