# Shopify/restyle: a type-enforced theming layer for React Native

> Restyle is a TypeScript library for building React Native UI components against a design system of colors and spacing. It is a library for building UI libraries, and the README is candid that it works best when one-off values stay rare.

**Shopify/restyle** — A type-enforced system for building UI components in React Native with TypeScript.

- Repository: https://github.com/Shopify/restyle
- Website: https://shopify.github.io/restyle/
- Stars: 3,425 · Forks: 150
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/shopify-restyle

## The problem Restyle targets: one-off style values that escape the design system

Most React Native codebases start with a palette and a spacing scale, then slowly lose them. A screen needs a slightly different grey, someone writes the hex inline, and six months later nobody can tell which values are part of the system and which were an exception. Restyle's answer is to make the theme the only source of style values and let the type checker enforce it. The README frames the library as a type-enforced system for building UI components in React Native with TypeScript, and calls it a library for building UI libraries, with themability as the core focus. That second phrase is the important one. Restyle is not aimed at the app developer who wants a shortcut for writing styles. It is aimed at the person who owns the component layer that everyone else imports. The README states the library assumes the UI is built upon a design system that at minimum defines a set of colors and spacing constants. It also acknowledges that exceptions exist and allows any style to be overridden, while noting that the developer stays most productive when one-off values are kept to a minimum. That is an unusually honest framing for a styling library: the escape hatch is documented, and so is the cost of using it.

## How the constraint-based props work

The package.json describes the project as a system for building constraint-based UI components. Constraint-based means the props you pass to a component are not free-form style objects; they are keys into the theme. You define a theme object, and the components derived from it accept props whose values are checked against that theme's shape. The README points to styled-system as the direct inspiration, and the repository keeps a fixture app as a working example of the pattern. The build output is a single compiled package: package.json sets main to dist/index.js and types to dist/index.d.ts, and the files field publishes only dist/*, so consumers get compiled JavaScript and declaration files rather than source. The library is marked sideEffects: false, which matters to bundlers doing tree shaking. The peer dependencies are react and react-native, both wildcarded, which means Restyle does not pin your framework versions and does not ship its own copy. In practice that is the right call for a library at this layer, but it also means version conflicts are your problem, not the package's.

## Installing Restyle and defining a first theme

The README lists three equivalent installation commands. Pick the one that matches your package manager; the Expo variant is listed alongside the plain npm and yarn forms.

```bash
yarn add @shopify/restyle
```

```bash
npm install @shopify/restyle
```

```bash
npx expo install @shopify/restyle
```

After installation you create a theme and derive components from it. The README does not inline a full usage example, directing readers to the Usage page of the documentation site and to the fixture app instead, so the exact import names and the full prop list are best taken from those two sources rather than guessed. What the repository does show is the shape of the workflow: a theme object holding at least colors and spacing, a provider that makes that theme available, and components that read from it. The fixture directory is the reference implementation to copy from. If you want to run the documentation site locally, the README gives these steps.

```bash
cd documentation
yarn
yarn start
```

The site then serves at http://localhost:3000/restyle/. Running the fixture app itself is done through the scripts in the root package.json, which build the library first and then delegate to React Native.

## Where Restyle is the wrong tool

Restyle assumes a design system exists. If your team has not agreed on a color set and a spacing scale, the library has nothing to constrain you to, and you will spend the first week arguing about token names instead of shipping screens. The README is explicit that one-off values should be kept to a minimum, which is a polite way of saying the library fights you when your design does not fit the system. A marketing screen with a bespoke layout, an animation-driven onboarding flow, or a one-screen promotion will be easier to write with plain StyleSheet than with themed props. The override path exists, but using it everywhere defeats the purpose of adopting the library. There is a second boundary worth naming: Restyle is React Native only. The peer dependencies are react and react-native, and nothing in the repository suggests a web target. If you are sharing components between a React Native app and a React web app, Restyle will not be the shared layer. Finally, the release cadence is worth checking against your own upgrade tolerance. The most recent release listed is v2.4.5 from 2025-03-19, preceded by v2.4.3 in 2024 and v2.4.2 in 2023. The repository is not archived and the last push was on 2026-09-18, but the published version numbers move slowly, so a fix you need may sit on master for a while before it reaches npm.

## Restyle against styled-components and plain StyleSheet

The closest comparison is styled-components for React Native. That library lets you write CSS-like template strings and attach them to a component, and it handles theming through a ThemeProvider that injects values at runtime. The difference in approach is where the checking happens. With styled-components, a mistyped color is a runtime lookup that returns undefined and renders wrong. With Restyle, the prop value is typed against the theme, so a color key that does not exist is a compile error. That is the whole argument for the library, and it is a real one in a large codebase. The trade-off is expressiveness: template strings can describe anything CSS can, while constraint-based props only describe what your theme models. The other comparison is doing nothing at all and using React Native's built-in StyleSheet. That is lighter, has no peer dependency surface, and requires no theme object. It also gives you no mechanism to stop the drift the README describes. Restyle sits between the two: less flexible than styled-components, more enforceable than StyleSheet, and only worth the dependency if the enforcement is the thing you actually need.

## Licence, maintenance and the cost of upgrading

Restyle is MIT licensed, with LICENSE.md at the repository root and the license field in package.json set to MIT. For most teams that is the permissive end of the spectrum and carries few obligations beyond retaining the notice. This is not legal advice; check the file itself if your organisation has specific requirements. On maintenance, the facts are these: the repository is not archived, and the last push was on 2026-09-18. Releases are less frequent than commits, with v2.4.5 in March 2025 and the prior two in 2024 and 2023. The README links to a migration guide for v2, which tells you the project has already been through at least one breaking change and documented the path. Upgrading across a major version is therefore a known exercise rather than an unknown one, but the guide is the thing to read before you start. The dependency surface is small: react and react-native as peers, and the published package contains only the compiled dist directory. That keeps install size and transitive risk low, which in turn keeps the upgrade cost mostly about your own theme and component code rather than about the library's internals.

## Conclusion

Adopt Restyle if you are building a React Native app or an internal component library on top of a design system that already defines colors and spacing, and you want TypeScript to reject a stray hex value at compile time. Do not adopt it if your UI is largely bespoke screens with per-screen styling, or if you are not on React Native at all: the peer dependencies are react and react-native, and the README describes the library as assuming a design system with at least colors and spacing constants. Before committing, verify that the theme shape you need maps onto the constraint-based props the documentation lists, and check the fixture app to see how a real screen is assembled.

## FAQ

### What is @shopify/restyle?

It is a type-enforced system for building UI components in React Native with TypeScript, described in its package.json as a system for building constraint-based UI components. The README calls it a library for building UI libraries, with themability as the core focus.

### How do I install @shopify/restyle?

The README lists three options: yarn add @shopify/restyle, npm install @shopify/restyle, or npx expo install @shopify/restyle. Usage examples live on the documentation site and in the fixture app rather than in the README.

### Does @shopify/restyle require a design system?

The README states the library assumes the UI is built upon a design system that at minimum defines a set of colors and spacing constants. It allows any style to be overridden, but notes that developers stay most productive when one-off values are kept to a minimum.

### What is @shopify/restyle licensed under?

MIT, per the license field in package.json and the LICENSE.md file at the repository root.

## Sources

- [License: MIT](https://github.com/Shopify/restyle/blob/master/LICENSE)
- [Project website](https://shopify.github.io/restyle/)
- [README](https://github.com/Shopify/restyle/blob/master/README.md)
- [Releases](https://github.com/Shopify/restyle/releases)
- [Shopify/restyle on GitHub](https://github.com/Shopify/restyle)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shopify-restyle