React-styleguidist: Ability to ignore components

[sapegin]

Array of regexp masks or function.

[mik01aj]

Or maybe a glob pattern? See: https://github.com/isaacs/node-glob#options

Then, instead of:

componentSources = glob.sync(path.join(config.rootDir, config.components));

you could do:

componentSources = glob.sync(config.components, {
    cwd: config.rootDir,
    ignore: config.ignorePatterns,
});

[sapegin]

Nice, didn’t know about that!

[mik01aj]

And maybe even this feature is not necessary at all as you can use a function directly in the config. We'd just need to add an example to the README.

[sapegin]

That’s even better. Can you make a PR for that?

[sapegin]

(Actually you can commit directly to the repo now ;–)

[panayi]

An additional configurable option that may be useful, is to be able to include components only when a sibling .md file is present.

// styleguide.config.js
module.exports = {
  // ...
  // ...
  getExampleFilename: function(componentpath) {
    return componentpath.replace(/\.jsx?$/, '.md');
  },
  components: function(config, glob) {
    const regex = /\/[A-Z][A-Za-z]*\.jsx$/
    return glob.sync(config.rootDir + '/**/*.jsx').filter(function(module) {
      const mdFile = config.getExampleFilename(module);
      try {
        const mdFileWithSameNameExists = fs.statSync(mdFile);
        return mdFileWithSameNameExists && mdFileWithSameNameExists.isFile();
      } catch(err) {
        return !(err && err.code === 'ENOENT');
      }
    });
  }
}

[sapegin]

@panayi Yeah, pull request for that would be very helpful.

[panayi]

I'm thinking of two options:

1. A config option includeOnlyComponentsWithExampleFile:true|false, or something shorter, examples: 'required'
2. A webpack-loader type of syntax: hasExample that can be passed in components

module.exports = {
  components: 'hasExample!/**/*.jsx'
}

In case components is a function we can also provide a helper hasExample function:

module.exports = {
  components: function(config, glob) {
    const regex = /\/[A-Z][A-Za-z]*\.jsx$/
    return glob.sync(config.rootDir + '/**/*.jsx').filter(function(module) {
      return config.hasExample(module);
      // alternatively the package exports the function and...
      // import { hasExample } from 'react-styleguidist'
      // return hasExample(module)
    });
  }
}

[sapegin]

Not sure the second options has any benefits but it’s much more complicated.

includeOnlyComponentsWithExampleFile → skipComponentsWithoutReadme?

[panayi]

You are right that the 2nd option is unnecessary complex. Implemented 1st option: https://github.com/sapegin/react-styleguidist/pull/38

[mik01aj]

imho skipComponentsWithoutReadme name is not so relevant, because the Readme.md name can be changed in the config to anything else. We have getExampleFilename in config, so why not skipComponentsWithoutExample (or ...examples - the pluralization is not consistent anyway)?

[sapegin]

@mik01aj good point, I didn’t think about that.

[mik01aj]

I guess this ticket can be closed now.

[sapegin]

We should document ignoring. I think we can add a section like _Recipes_ for such things. So I’ll leave it open for now ;-)

[operatino]

In SourceJS, during navigation tree build I only search for component folders with some hook inside, like info.json. Maybe in this case it also be wise to include by default only those components, which have readme.md next to it?

[sapegin]

There’s an option to do that — skipComponentsWithoutExample ;-)

[jamieholliday]

So I have skipComponentsWithoutExample: true in config but just noticed a weird behaviour when having nested components
I have these 3 components:
Grid
Row
Column
In Grid/Readme.md I have this:

const Row = require('components/Row');
const Column = require('components/Column');
const Grid = require('components/Grid');
<Grid>
  <Row>
    <Column>
    ....
    </Column>
  </Row>
</Grid>

It now doesn't matter if I have Readme.md files in any of the other component folders or not I get the entries for all 3 components in the styleguide and duplicate example code for each. I'd like to have different example for each component by supplying different Readme files or even just ignore the <Row /> and <Column /> components completely from styleguide.

EDIT: Ok this turned out to be an issue with the requires using the wrong path and not being loaded

[AoDev]

Could we add a directive in a comment at the top of a component file like many linters do for example?

/*react-styleguide: ignore*/

import React from 'react'

... component code

[mik01aj]

Why would this be better than ignoring the components in the styleguide config?

[sapegin]

It also might be difficult to implement. And I’d like to have a style guide config as isolated from the code as possible.

[AoDev]

Because right now the styleguide is also documenting some "internal" subcomponents which shouldn't be a concern for the developers who are going to use the main component.

[mik01aj]

@AoDev this doesn't answer my question. I didn't ask you why we need ignoring components, I asked you why do you want to do it in the component file instead of the styleguide config (see the comments above for details on how to do it).

[AoDev]

Because it's easier to do for the user. Regarding the styleguide config you'd need to create a function / pattern that is heavily dependent on the file names / pattern / file structure.

Files operations like renaming files / moving code around (that sure does not happen all the time), need to be followed by a change in the styleguide config while there wouldn't be anything to do with this directive.

[AoDev]

But, if you have code pattern structure to propose to help it's more than welcomed.
Our structure is similar to AirBnB react styleguide. https://github.com/airbnb/javascript/tree/master/react#naming

[mik01aj]

Well, yes, but the same is also true for most build, or test, or lint configs. I still think it's fine as it is.

[sapegin]

I’ve added to the FAQ how to ignore components using the components option.

I’m closing this for now. Feel free to submit a pull request if you need a simpler way to ignore components.

[dfredriksen]

Link to FAQ is broken