{"id":20145,"library":"isomorphic-style-loader","title":"Isomorphic Style Loader","description":"Webpack loader for CSS that optimizes critical path rendering and supports isomorphic (universal) React apps. Current stable version is 5.4.0, released April 2022. Works like style-loader but allows server-side collection of CSS strings via _getCss() and client-side injection via _insertCss(). Uses React Context API (StyleContext) with insertCss callback. Requires React 16.8+ and css-loader. Features withStyles HOC and useStyles hook for React components. Alternative to style-loader when SSR is needed.","status":"active","version":"5.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/kriasoft/isomorphic-style-loader","tags":["javascript","webpack","webpack-loader","webpack loader","loader","css","scss","style","styles"],"install":[{"cmd":"npm install isomorphic-style-loader","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic-style-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic-style-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency – provides React Context and hooks (useStyles, withStyles)","package":"react","optional":false},{"reason":"Peer dependency – used for server-side rendering (renderToString)","package":"react-dom","optional":false}],"imports":[{"note":"Subpath import required; default export is the loader, not withStyles.","wrong":"import withStyles from 'isomorphic-style-loader'","symbol":"withStyles","correct":"import withStyles from 'isomorphic-style-loader/withStyles'"},{"note":"Hook exported as a default export from 'isomorphic-style-loader/useStyles'.","wrong":"import { useStyles } from 'isomorphic-style-loader'","symbol":"useStyles","correct":"import useStyles from 'isomorphic-style-loader/useStyles'"},{"note":"Must be imported from subpath; StyleContext is a React Context object.","wrong":"import { StyleContext } from 'isomorphic-style-loader'","symbol":"StyleContext","correct":"import StyleContext from 'isomorphic-style-loader/StyleContext'"}],"quickstart":{"code":"// webpack.config.js\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.css$/,\n use: [\n 'isomorphic-style-loader',\n { loader: 'css-loader', options: { importLoaders: 1, modules: true } },\n 'postcss-loader'\n ]\n }\n ]\n }\n};\n\n// App.js\nimport React from 'react';\nimport withStyles from 'isomorphic-style-loader/withStyles';\nimport s from './App.css';\n\nfunction App() {\n return Hello
;\n}\n\nexport default withStyles(s)(App);\n\n// server.js\nimport express from 'express';\nimport React from 'react';\nimport ReactDOM from 'react-dom/server';\nimport StyleContext from 'isomorphic-style-loader/StyleContext';\nimport App from './App.js';\n\nconst server = express();\nserver.get('*', (req, res) => {\n const css = new Set();\n const insertCss = (...styles) => styles.forEach(style => css.add(style._getCss()));\n const body = ReactDOM.renderToString(\n \n \n \n );\n const html = `${body}
`;\n res.send(html);\n});\nserver.listen(3000);","lang":"javascript","description":"Shows webpack config, component with withStyles, and SSR setup using StyleContext and insertCss callback."},"warnings":[{"fix":"Use import from 'isomorphic-style-loader/withStyles' (without /lib/) and wrap app in StyleContext.Provider.","message":"Upgraded React Context API in v5, breaking older withStyles usage from 'isomorphic-style-loader/lib/withStyles'.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure react and react-dom are installed as regular dependencies or peer dependencies.","message":"React moved to peer dependencies in v5.2.0-beta.1; earlier versions bundled React.","severity":"breaking","affected_versions":">=5.2.0-beta.1"},{"fix":"Always use subpath imports: 'isomorphic-style-loader/withStyles', 'isomorphic-style-loader/useStyles', etc.","message":"Default export from 'isomorphic-style-loader' is the Webpack loader function, not a React utility. Importing 'isomorphic-style-loader' as a module will not give you withStyles.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"In client-side only builds, ensure StyleContext provider is set up with a insertCss function that calls styles._insertCss().","message":"Browser usage without SSR: if not using StyleContext, styles won't be injected because insertCss is not called.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Check documentation for configuring HMR in webpack; no breaking change but behavior differs.","message":"HMR (Hot Module Replacement) now output on demand; old behavior may have been automatically injecting.","severity":"deprecated","affected_versions":">=5.4.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm install isomorphic-style-loader --save-dev' and ensure import uses correct subpath, e.g., 'isomorphic-style-loader/withStyles'.","cause":"Forgetting to install the package or incorrect import path.","error":"Module not found: Error: Can't resolve 'isomorphic-style-loader'"},{"fix":"Ensure the webpack rule uses 'isomorphic-style-loader' and not 'style-loader'. The style object has _getCss and _insertCss methods.","cause":"Using the style object incorrectly – likely imported from style-loader instead of isomorphic-style-loader.","error":"TypeError: styles._getCss is not a function"},{"fix":"Wrap your app in with a valid insertCss function.","cause":"Missing StyleContext.Provider or insertCss callback not passed.","error":"Warning: Failed context type: The context `insertCss` is marked as required in `withStyles`, but its value is `undefined`."},{"fix":"Use withStyles(styles)(Component) or withStyles(styles)(React.forwardRef(...)).","cause":"Calling withStyles(styles) without wrapping a React component.","error":"Invariant Violation: withStyles requires a React component"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}