The styled-components website is the library documenting itself, and it runs on a v7 prerelease

This is the documentation site, not the library

The styled-components website is the documentation site for styled-components, and it is worth being clear about that before reading anything else, because the repository name invites confusion.

The project description says it plainly: the styled-components website and documentation. The README title is styled-components.com, and the site is built with Next.js, Preact and, in its own phrase, of course, styled-components. The homepage is styled-components.com, the primary language is TypeScript, the licence is MIT, and the last push was on 2026-09-11.

So this is where the library explains itself, and where people file issues asking for better documentation. The README invites contributions directly, pointing at the issues list for ideas on what to work on, and it links the Next.js learning material, the Next.js documentation and the styled-components documentation itself, which it notes is this very website.

That last link is the interesting loop. A library that documents itself with itself is a reasonable way to keep the documentation honest, because the code samples in the docs are rendered by the same runtime the reader will install. The dependency list confirms it: styled-components is a direct dependency of the site, alongside stylis and stylis-plugin-rtl, which are the CSS preprocessing layers the library builds on, and prism-react-renderer and react-live-runner, which are what make a code block in the documentation a live, editable example rather than a picture of one.

The repository is not archived, there are no GitHub releases, and the top level entries show a conventional modern site: an app/ directory for the router, components/, sections/, lib/, scripts/, test/, public/, assets/ and utils/.

Next 16, React 19 and a prerelease of the library it documents

The dependency versions tell you how current the site is, and one of them is worth pausing on.

Next is pinned at 16.2.6, React and React DOM are on 19.2.6, and the documentation is written in MDX with the @mdx-js packages and the Next MDX integration. Styling the docs is done with styled-components plus styled-theming, and the site uses react-transition-group for the transitions in the page chrome.

The line to notice is the library itself: styled-components 7.0.0-prerelease-20260731035917. The site builds against a prerelease of styled-components, tagged with a timestamp rather than a clean version number.

That is defensible. A documentation site is the natural place to prepare for a major version, and shipping the docs against the prerelease means the documentation and the release land together. It also means the site is not a reference for the currently released version, and any example a reader copies from it may use an API that has moved by the time they install it.

The type definitions tell a slightly different story. The devDependencies include @types/styled-components at 5.1.36, which is the DefinitelyTyped package for the 5.x line, while the runtime dependency is a 7.x prerelease. So the site is written against a newer library than the published type definitions describe, and that combination usually works because the types are only consulted for the site itself, but it is a visible sign that the version boundary is still in progress.

The rest of the stack is ordinary and well chosen. Algolia Docsearch provides the search, caniuse-lite is present for browser support data, and there is a server-only package to stop server code leaking into the client bundle, which is a small sign of care about bundle boundaries. The overrides block pins @types/react to 19 and react-simple-code-editor to an exact version.

Four commands to run the site locally

The local setup is documented in full, which is the mark of a project that expects outside contributions.

# Download the repo
git clone https://github.com/styled-components/styled-components-website
# Enter the repo
cd styled-components-website
# Install the dependencies
pnpm install
# Start local development
pnpm dev

The requirements are Node.js and pnpm, both set up locally, and the note links nodejs.org for more information. The package metadata pins the package manager through pnpm-lock.yaml, and there is a .nvmrc file and an .npmrc file, so the expected Node version and registry settings live with the repository rather than in a wiki page.

The dev script is next dev --turbopack, which is the fastest path to see a change. The production path mirrors it, with the build running as NODE_ENV=production next build and the start script running next start with the same environment. A prebuild script removes the .next directory first, so a stale build directory is never the reason your change did not appear.

The rest of the scripts are the housekeeping of a modern repository, and they are worth listing because they tell you what a contribution is expected to pass. The test script runs jest with the configuration in .jest.config.js. Formatting is handled by oxfmt with a format:check variant, linting by oxlint, and there is a precommit script that runs lint-staged, a prepare script that installs the husky hooks, and a .husky/ directory in the tree.

So the local loop is install, develop, and let the hooks and the test suite tell you whether the change is acceptable. That is a well set up contribution path for a documentation site, where the bar is usually higher than it needs to be because the site is the product.

The visual diff snapshots are the review gate

The most distinctive thing about this repository's workflow is that it takes pictures of itself.

The README has a section on updating the visual diffs. If you add a new section or materially change the website, it will probably trigger the image comparison diff snapshot to fail, and those can be updated with:

pnpm test -- -u

This is a screenshot test suite, and it is the reason a change to a documentation site is reviewable at all. A documentation change is usually a text change, and text changes are invisible in a diff. If someone changes the width of a container or a colour token, the prose diff shows nothing at all and the reviewer has to run the site to notice.

The screenshot suite turns that class of change into a visual diff, so a reviewer sees the before and after images and can check whether the change was intended. The cost is that the suite has to be updated deliberately whenever the site is meant to look different, which is exactly why the instruction is spelled out rather than left to a failing test message.

The test/ directory at the root and the .jest.config.js file hold the configuration, and the devDependencies show the testing stack: Jest with the Testing Library packages for DOM and React, jest-dom for the custom matchers, and @testing-library/react. The styled-components types are also present in the devDependencies.

For a contributor, the practical sequence is: make the change, run the tests, look at the image diff, and if the change was meant to alter the appearance, update the snapshots deliberately rather than reflexively.

The folder guide in the README is out of date, and that is a real hazard

The README includes a folder structure section, and it is the part of the documentation most likely to mislead a new contributor.

It describes six directories: components/ for shared components, pages/ for the actual pages with the directory correlating directly to the URL, for example pages/docs/basics.js mapping to styled-components.com/docs/basics, sections/ for the content written in Markdown, public/ for assets, test/ for tests, utils/ for utilities, and vendor/ for cached dependencies.

The repository's actual top level tells a different story. There is an app/ directory, which is the Next.js App Router convention, and no pages/ directory at the root. There is also a lib/ directory, a scripts/ directory, an assets/ directory, and a mdx-components.tsx file at the root, which is the conventional place to map MDX components. The vendor/ directory is not in the top level listing either, and the README's own text for pages/ refers to files with a .js extension, which is also older than the TypeScript setup the package metadata describes.

So the folder guide in the README documents a structure the project has moved away from. That is an ordinary kind of documentation drift, and it is worth calling out because the failure mode is quiet: a contributor follows the guide, creates pages/docs/basics.js, and nothing routes to it.

The parts of the guide that are still accurate are the parts that describe content rather than routing. sections/ for Markdown content is still how the documentation body is written, components/ for shared components, utils/ for utilities, and public/ for assets all still match. The routing convention is the part to verify against the app/ directory before you add a page, and the mdx-components.tsx file at the root is the place to look for how MDX elements are mapped.

Agent instruction files, a manifest of companies and a fan comment thread

A few things in the repository tree show what kind of project this is, and they are not the usual library components.

There is an AGENTS.md file and a CLAUDE.md file at the root, plus a .cursor/ directory. Whatever those contain, their presence means the repository is written to be worked on by automated coding agents as well as by people, and it is the first place a contributor should look for the rules of the house.

There is a companies-manifest.tsx file at the root, which is presumably the list of companies shown on the site, and a caniuse-lite.d.ts type declaration. The dependency on bluesky-comments shows that the site hosts a comments thread powered by Bluesky, which is an unusual choice for a library documentation site and suggests the authors want discussion to live somewhere that is not a comment system tied to a single vendor account.

The .cursor/ directory, the .husky/ directory with its git hooks, .lintstagedrc.js, .oxlintrc.json and .oxfmtrc.json together describe a repository where formatting and linting are enforced before a commit lands, and .prettierignore, .editorconfig, .vscode/ and .gitignore cover the rest of the daily workflow.

Two files are conspicuously absent from the tree listing. There is no CHANGELOG.md, which makes sense for a documentation site, and there is no SECURITY.md either, even though that file exists in most of the projects in this space. The security contact for the library itself therefore lives elsewhere, which is worth knowing if you find a problem with how the site handles something.

MIT terms, no releases, and a site that tracks the library's cadence

The licence is MIT and the package is marked private, so nothing here is published to a registry. There are no GitHub releases, which is the right shape for a site whose unit of delivery is a commit that the platform builds.

The deployment path is not described in the visible documentation, but the tree gives it away. There is a vercel.json file, which is the configuration Vercel reads, and a next.config.mjs, and the repository is styled-components-website with the styled-components organisation, so the site is deployed on Vercel like most Next.js projects.

What the repository does not say is as relevant. The README does not describe how to add a new documentation page end to end, which is the question a first contribution usually has, and it does not explain how the content in sections/ is wired into the MDX pipeline beyond the folder guide. Both are answerable from the code, but neither is documented, which puts the cost on the contributor.

The main thing to check before working here is the version alignment. The site builds against a 7.0.0 prerelease of styled-components, the type definitions are on the 5.x line, and the content in sections/ describes whichever version the maintainers were writing about when it was last touched. If your contribution is documentation for a released version, check what the site currently says before you write, because the site may already describe the behaviour of the prerelease.

Editorial conclusion

Use this repository if you want to contribute to the styled-components documentation, since it is the site, the content and the tooling in one place and the local workflow is four commands. Do not treat it as a reference implementation of styled-components, because the site pins a 7.0.0 prerelease of the library and its own type definitions are still on the 5.x line, so code copied from here may not match a released version. Before you start, read AGENTS.md, run pnpm install and pnpm dev, and check the styled-components version the site actually builds against against the version you intend to document.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. styled-components/styled-components-website on GitHub