React-styleguidist: How does your team use Styleguidist?

[apennell]

I'd love to hear how folks are actually implementing the components developed with React Styleguidist! How is your app configured? What's your build pipeline? Did you make it an NPM package for use in other apps? How are you packaging it for external use? How are you compiling your components? Do you use CSS Modules? Are your styles tied to their individual component and used with a simple import { Component } from 'my-guide'; or is including a separate link to the stylesheet necessary? Do you have an example repo you can share that shows your configuration?

I was able to get a component library built that renders the styleguide as expected, and the components are also properly rendering when added to the basic App.js component that comes with create-react-app (which was the foundation of my library app) and is within the same src/ folder as my components. However, I've struggled to package it so that the components appear as expected in other apps when included as a GitHub package. I could get the components working and using the props but it wasn't getting the CSS. I'm using CSS Modules for the styling but am clearly not bundling it right with Webpack. I'd like to be able to just include the component without have to require a stylesheet link separately.

If anyone feels like looking at my particular situation, here is an example repo I made with my current configuration. There’s a lot of documentation on working with it in the Readme. You can clone this basic app with the component library implemented. src/app.js uses <Button /> from annies-component-lab.

Even if no one looks at mine and gives me a specific answer, I think it would be really helpful to hear from others how they're using their app built with Styleguidist and the specifics of their configuration. This could be a good discussion to be available for folks in the future struggling with this.

Thanks!

[n1313]

The team I'm in is using RSG to develop a set of UI components for a fairly large international company. We distribute it internally via our private npm repository. RSG is used by us during development as an interactive playground, and the compiled documentation bundle is published to an internal website so that our potential users can take a look at it and see how it looks and works in real life. RSG is not included in our npm package.

We write in ES6 and use SCSS, CSS Modules and react-themr for styling. We compile our code to ES5 UMD bundle with static assets (CSS files, SVGs, fonts, ets) as separate files using webpack, so our consumers have to manually insert our files into their pages somehow, either with a <style>/<script> tags or by appropriately inserting it into their build process. I think in order to get the styles automatically injected together with your components you will have to bundle the stylesheet together with your js (so no ExtractTextPlugin shenanigans).

[sapegin]

Our approach is very similar to @n1313. The main difference is that we only transpile ES6 to ES5 (TypeScript in the future) and keep CSS Modules as is. Which means we need to include component library’s package folder into css-loader?modules. But it allows us to include into the app bundle only CSS and JS of components that we actually use.

Here’s a webpack block that we use for CSS. I can share more configs is you like.

[ghost]

Is it possible to see the Kao Style Guide Repo?

[sapegin]

@joergklein No, sorry, it’s not public. But I can share some configs.

[ghost]

Is it possible to publish a running basic system and the Button components in a separate Github repo? Readme.md, Button.css, Button.js and index.js. It would be very helpful.

[n1313]

@joergklein there are examples in this repo, are they not enough?

[stepancar]

@apennell @joergklein
You can see our base webpack config for web application based on our ui-library arui-feather
Also all another configs like postcss, babel, eslint, stylelint, tslint, tsconfig which we use in our projects you can find in this repo
We don't use css modules, we use bem using cn-decorator
Our private ui-component libraries and arui-feather
publish with library-utils - library which generate readme.md files, package.json, typescript definitions and source maps for each component

[Jmeyering]

We have implemented RSG in conjunction with Styled Components. Right now we are waiting on https://github.com/reactjs/react-docgen/pull/198 to get merged into react-docgen so that we are able to use styled components natively, however we have shimmed a patched fork into our system to enable it to work for now.

Styled Components are really great for packaging CSS because there is no external bundling required in the build step. This gives us immense portability / flexibility because the styles are directly declared within the component file.

[apennell]

Thanks for your input everyone! It seems like @n1313 was pointing me in the right direction with the suggestion of no ExtractTextPlugin. I made a new config based on the gist that @sapegin posted and this sample webpack.config from css-modules, but the problem persisted. In this case the classes weren't transformed and included on the components.

@sapegin You mentioned being able to share additional configs. Is there anything else you can share that might help? I also noticed that you still used ExtractTextPlugin and am curious about that, because it seemed like that was what was pulling out my CSS into a separate file initially.

[sapegin]

OK, I’ll try ;-)

First, the component library:

// package.json
"scripts": {
  "build": "npm run build:compile && npm run build:copy",
  "build:compile": "NODE_ENV=production babel ./lib --out-dir ./dist --ignore '__tests__,*.spec.js'",
  "build:copy": "cpy '**/*.scss' '../dist' --cwd lib --parents",
  "prepublishOnly": "npm run build"
},

No webpack, not touching CSS Modules, just transpiling ES6 and copying CSS files as is.

Now, the app:

// webpack.config.js
const path = require('path');
const ExtractTextPlugin = require('extract-text-webpack-plugin');
const {
    createConfig,
    env,
    entryPoint,
    sourceMaps,
    setOutput,
    css,
    babel,
    uglify,
    devServer,
} = require('webpack-blocks');

const file = f => path.resolve(__dirname, f);

const isProd = process.env.NODE_ENV === 'production';

// Path of your component library inside node_modules
const kaoPath = path.resolve(__dirname, 'node_modules/@here/kao/dist');

/**
 * Sass webpack block with optional CSS Modules. Supports TypeScript and Kao.
 *
 * @param {string[]} $.include Source code folder
 * @param {boolean} $.modules Enable CSS Modules
 * @returns {function}
 */
function sass({ include, modules = false }) {
    const localIdentName = isProd
        ? '[hash:base64:10]'
        : '[name]--[local]--[hash:base64:5]';
    const loaders = [
        modules ? {
            loader: 'css-loader',
            options: {
                modules: true,
                importLoaders: 1,
                localIdentName,
            },
        } : (
            'css-loader'
        ),
        'postcss-loader',
        {
            loader: 'sass-loader',
            options: {
                precision: 10,
            },
        },
    ];
    return (context, { merge }) => merge({
        module: {
            rules: [
                {
                    test: /\.scss$/,
                    use: isProd
                        ? ExtractTextPlugin.extract({
                            fallback: 'style-loader',
                            use: loaders,
                        })
                        : ['style-loader'].concat(loaders),
                    include: modules
                        ? [include, kaoPath]
                        : include,
                },
            ],
        },
    });
};

/**
 * Extract CSS to a separate file, require ExtractTextPlugin.extract in loaders.
 *
 * @returns {function}
 */
function extractCss() {
    return (context, { addPlugin }) => addPlugin(
        new ExtractTextPlugin({
            filename: '[name].[chunkhash].css',
            disable: !isProd,
            allChunks: true,
            ignoreOrder: true,
        })
    );
};

module.exports = createConfig([
    babel(),
    css(),
    sass({
        include: file('assets/stylesheets'),
    }),
    sass({
        include: file('assets/javascripts'),
        modules: true,
    }),

    setOutput({
        buildDir: file('../tmp/webpack-build'),
        publicPath: '/assets/',
    }),

    env('development', [
        entryPoint(file('scripts/development.js')),
        devServer(),
        sourceMaps(),
    ]),

    env('production', [
        entryPoint(file('scripts/production.js')),
        extractCss(),
        uglify(),
    ]),
]);

The actual set up is more complicated so it may not work if you try to use this code as is.

[stale[bot]]

😴 This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week without any further activity. Thank you for your contributions.