Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace html-webpack-plugin with mini-html-webpack-plugin #896

Closed
sapegin opened this issue Mar 27, 2018 · 7 comments
Closed

Replace html-webpack-plugin with mini-html-webpack-plugin #896

sapegin opened this issue Mar 27, 2018 · 7 comments
Assignees
Milestone

Comments

@sapegin
Copy link
Member

sapegin commented Mar 27, 2018

Pros

  • Much simpler but enough for our use case.
  • Users could use any version of html-webpack-plugin and it won't break Styleguidist.
  • Use mini-html-webpack-template to customize template without replacing the whole HTML file (that should be enough for most use cases for custom templates).

Cons

  • Breaking change because existing custom templates won’t work (actually template files won’t be supported at all but a template function + mini-html-webpack-template options).

API proposal

template options won’t accept a string but an object that will be passed to the context options of mini-html-webpack-template. We’ll need to overwrite some properties in this object like title or container.

module.exports = {
  template: {
    head: {
      links: [
        {
          rel: 'shortcut icon',
          href: 'https://assets-cdn.github.com/favicon.ico',
          type: 'image/x-icon'
        }
      ]
    }
  }
}

Or a function that will receive title, container, etc. and return an HTML string.

More details

@sapegin sapegin added this to the 7.0.0 milestone Mar 28, 2018
@sapegin sapegin self-assigned this Mar 28, 2018
@n1313
Copy link
Collaborator

n1313 commented Mar 29, 2018

What would be the benefit of this change for users who already have custom templates?

@sapegin
Copy link
Member Author

sapegin commented Mar 29, 2018

@n1313 That's not the right question: they will have to update their config. Benefits are for new users and maintainers.

sapegin added a commit that referenced this issue Mar 31, 2018
👋 **[Support Styleguidist](https://opencollective.com/styleguidist) on Open Collective** 👋

## Breaking changes

### Node 6 is the lowest supported version

Styleguidist doesn’t support Node 4 anymore.

(#744 #839 by @kohgpat)

### New format of template option

We’re now using [mini-html-webpack-plugin](https://github.com/styleguidist/mini-html-webpack-plugin) and [@vxna/mini-html-webpack-template](https://github.com/vxna/mini-html-webpack-template) instead of [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin).

This will make things like [adding a favicon](https://react-styleguidist.js.org/docs/cookbook#how-to-add-a-favicon) or fonts from [Google Fonts](https://react-styleguidist.js.org/docs/cookbook#how-to-add-fonts-from-google-fonts) much easier.

If you’re using a custom HTML template, you need to update your style guide config.

```js
// 6.x
module.exports = {
  template: './styleguie/template.html'
}

// 7.x
module.exports = {
  template: {
    // This is just an example, there are many more available options
    favicon: 'https://assets-cdn.github.com/favicon.ico'
  }
}
```

See more [in the docs](https://react-styleguidist.js.org/docs/configuration#template).

(#896 #907 by @sapegin)

### Changed Node API

`server` method now returns an object containing a webpack `Compiler` instance and the Styleguidist server, see examples [in the docs](https://react-styleguidist.js.org/docs/api.html#servercallback).

(#828 by @cmswalker)

## New features

### Webpack 4 support

Webpack 3 is still supported too.

(#857 by @kontrollanten, #900 #901 by @rubenmoya)

### Examples are wrapped in React.Fragment

You don’t need to wrap multiple JSX tags in a div anymore.

```jsx
// 6.x
<div>
  <Button primary>Primary button</Button>
  <Button secondary>Secondary button</Button>
</div>

// 7.x
<Button primary>Primary button</Button>
<Button secondary>Secondary button</Button>
```

(#840 #842 by @tizmagik)

## Bug fixes

* `components` option should accept arrays.
* Do not convert URLs in Markdown to auto links (#793).
* Improved accessibility (#893 by @gergely-nagy).

---

❤️ Huge thanks to @okonet to help with this release, [CI](#904) and [docs](#905) improvements.️ ❤️
@styleguidist-bot
Copy link
Collaborator

🎉 This issue has been resolved in version 7.0.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

@kopax
Copy link
Collaborator

kopax commented Apr 13, 2018

Hi guys, I am a bit stuck upgrading to 7.0.0.

I use to have an html file. How should I regornize my file ? I assume I need to replace styleguide/template.html previously:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title><%=htmlWebpackPlugin.options.title%></title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<div id="app"></div>
</body>
</html>

with styleguide/template.js

const MiniHtmlWebpackPlugin = require('mini-html-webpack-plugin');
const {
  generateCSSReferences,
  generateJSReferences
} = MiniHtmlWebpackPlugin;

const config = {
  plugins: [
    new MiniHtmlWebpackPlugin({
      context: {
        title: 'Custom template' // Available in the context below
      },
      template: ({ css, js, title, publicPath }) =>
        `<!DOCTYPE html>
          <html>
            <head>
              <meta charset="UTF-8">
              <title>${title}</title>
              <meta name="viewport" content="width=device-width, initial-scale=1.0">
              ${generateCSSReferences(css, publicPath)}
            </head>
            <body>
              <div id="app"></div>
              ${generateJSReferences(js, publicPath)}
            </body>
          </html>`
    })
  ]
};

Then now, how do I boot this configuration ?

const myTemplate = require('styleguide/template');
const webpack = require('webpack');
const path = require('path');
const pkg = require('./package.json');

module.exports = {
  styleguideDir: 'public',
  require: [path.resolve(__dirname, 'styleguide/setup.js')],
  components: 'src/**/*.js',
  previewDelay: 500,
  skipComponentsWithoutExample: false,
  showCode: false,
  showUsage: true,
  showSidebar: true,
  styles: {
    Markdown: {
      pre: {
        border: 1,
        background: '#363438',
      },
      code: {
        fontSize: 14,
        fontWeight: 'bold',
        color: '#a280ed',
      },
    },
  },
  template: path.join(__dirname, 'styleguide/template.html'), // OK so this as to be a function, while I export a plugins, how do I call it ?
  theme: {
    color: {
      link: '#4c279e',
      linkHover: '#a280ed',
    },
  },
  title: `${pkg.description || pkg.name} documentation`,
  verbose: false,
  webpackConfig: {
    plugins: [
      new webpack.SourceMapDevToolPlugin({
        filename: '[file].map',
        exclude: [
          'node_modules/**/*.js',
        ],
      }),
    ],
    module: {
      rules: [
        // Babel loader, will use your project’s .babelrc
        {
          test: /\.jsx?$/,
          exclude: /node_modules/,
          include: [
            path.resolve(__dirname, 'src'),
            path.resolve(__dirname, 'styleguide'),
          ],
          loader: 'babel-loader',
        },
      ],
    },
  },
  styleguideComponents: {
    StyleGuideRenderer: path.join(__dirname, 'styleguide/components/LayoutRenderer'),
    Wrapper: path.join(__dirname, 'styleguide/components/Wrapper'),
  },
};

You should consider updating the documentation as well. We will downgrade to 6.x

@sapegin
Copy link
Member Author

sapegin commented Apr 16, 2018

@kopax Please point me to the docs that weren't updated? There are enough examples of the new API.

@kopax
Copy link
Collaborator

kopax commented Apr 16, 2018

@sapegin I was speaking of the release breaking change here :
https://github.com/styleguidist/react-styleguidist/releases/tag/v7.0.0

is there any extra documentation you are thinking about? I would gladly upgrade my styleguidedist.

@notgiorgi
Copy link

notgiorgi commented Jul 31, 2018

@n1313 That's not the right question: they will have to update their config. Benefits are for new users and maintainers.

So is there a way to use custom templates like ejs for index.html?

I need some assets from webpack to be rendered into index.html

@kopax did you downgrade or did you find another solution?

@styleguidist styleguidist locked as resolved and limited conversation to collaborators Jul 31, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

5 participants