The Next.js with styled-components example is an official boilerplate from the Next.js repository that swaps the default styled-jsx styling for styled-components while preserving universal server-side rendering of styles.
What is the Next.js with styled-components example?
It's an official starter project from Vercel's Next.js repository that configures styled-components for both server and client rendering. It takes a standard Next.js app, adds the babel-plugin-styled-components, extends pages/_document.js to inject SSR styles into the HTML head, and wraps the app in a ThemeProvider via pages/_app.js. The output is a working Next.js project where all CSS-in-JS styles are included in the first HTML response.
Key Features
The example delivers five concrete features that make styled-components work in Next.js.
- Server-side style injection — Extends the Next.js Document component to collect and render styled-components styles into
<head>, so the initial HTML includes all necessary CSS. - Mandatory Babel plugin — Includes
babel-plugin-styled-components, which the documentation states is required for server-side rendering. - Global theme provider — Adds a custom App component that wraps the application with
ThemeProvider, enabling a shared theme object across all components. - One-click Vercel deployment — Includes a deploy button that creates a new Vercel project pre-filled with the repository URL and project name.
- CodeSandbox integration — Provides a one-click link to open the example in CodeSandbox for browser-based testing.
- Link collision workaround — Documents a known issue with
next/linkand styled-components'asprop, with a solution usingforwardedAs.
Who is it for?
Developers building Next.js applications who want their CSS-in-JS styles to work with server-side rendering.
- Next.js developers — Those who prefer styled-components over the default styled-jsx and need the exact configuration to enable SSR-compatible styles.
- Developers migrating an existing app — Teams moving from styled-jsx or plain CSS to styled-components can copy this example's
_document.jsand_app.jssetup. - Design-system engineers — People who want to define a global theme once with
ThemeProviderand consume it across their app.
What can you do with it?
With this example you can scaffold a styled-components-based Next.js app and deploy it instantly.
- Scaffold a new project — Run
npx create-next-app --example with-styled-components with-styled-components-appto get a local dev server with styled-components preconfigured. - Deploy to production — Click the Deploy button to send the example to Vercel, which will automatically detect Next.js and run the build.
- Experiment online — Open the example in CodeSandbox and edit the styled components live without cloning the repository.
How does it work?
The setup relies on two file extensions and a Babel plugin.
First, pages/_document.js is extended to use ServerStyleSheet from styled-components, which collects all styles generated during server rendering and injects them into the <head> of the initial HTML. Second, pages/_app.js wraps every page in a ThemeProvider, making the theme available throughout the component tree. Finally, babel-plugin-styled-components is added to .babelrc so that the Babel transform works correctly with Next.js SSR.
FAQ
Is this example free?
Yes, it is an open-source example included in the official Next.js repository and is available under the MIT license.
Does this example support TypeScript?
No, the code in this example is JavaScript only. The Next.js repository offers a separate TypeScript version of the same example in other branches.
Does this example work with next/link?
There is a known collision when wrapping next/link in a styled-component because both use an as prop. The example recommends using the forwardedAs prop from styled-components or creating a custom Link wrapper.
How do I deploy this to my own server?
This example only provides the Vercel deployment path. You can use the standard Next.js build and start commands if you prefer to deploy elsewhere, but no custom server configuration is included.
