--- title: "StyleXとは？Meta製CSS-in-JSの導入手順と使い方【v0.19.1対応】" url: "https://www.issoh.co.jp/tech/details/2267/" published: 2024-05-24 updated: 2026-10-12 categories: ["フレームワーク"] publisher: "株式会社一創" --- # StyleXとは？Meta製CSS-in-JSの導入手順と使い方【v0.19.1対応】 StyleXはMetaが2023年12月5日にnpmで公開したスタイリングライブラリで、JavaScriptで書いたスタイルをビルド時にアトミックなCSSファイルへ変換します。2026年10月時点の最新版は2026年9月15日公開の0.19.1です。日本語の解説は公開直後の2023〜2024年のものが多く、非推奨になったNext.js用プラグインや、`npm install stylex`という無関係な別パッケージの手順が残っています。ここでは0.19.1を実際にコンパイルした出力と公式ドキュメントを根拠に、導入設定・書き方・型での制約・見送る条件を整理します。 ## まとめ - StyleXはBabelプラグインがビルド時にスタイルを抜き出し、静的なCSSを書き出す。実行時にstyleタグを生成しない。 - 入れるパッケージは`@stylexjs/stylex`。スコープなしの`stylex`は別作者の無関係なパッケージで、旧記事が使う`@stylexjs/nextjs-plugin`は0.12.0（2025年4月）で非推奨になった。 - Next.jsはBabel＋PostCSS、Vite・Webpack・Rspackは`@stylexjs/unplugin`で設定する。 - スタイルは`stylex.create`で定義し`stylex.props`で適用する。同じプロパティは最後に渡した側が勝ち、0.19.1の実出力でも負けた側のクラスはclass属性から消える。 - コンポーネントが受け取るスタイルは`StyleXStyles`の型引数で絞れる。0.19.1では`enableDebugClassNames`が削除され、開発時もクラス名は本番と同じハッシュになった。 ## ビルド時にCSSを書き出すStyleXの仕組み ### アトミックCSSへの変換とMeta社内の80%削減 StyleXのBabelプラグインは、ファイル内の`stylex.create`呼び出しを静的に解析し、「プロパティと値の組み合わせ」ごとに1つのクラスを作ります。`color: 'red'`を100か所に書いても、出力されるCSSルールは1つです。Metaのエンジニアリングブログ「[StyleX: A Styling Library for CSS at Scale](https://engineering.fb.com/2025/11/11/web/stylex-a-styling-library-for-css-at-scale/)」（2025年11月11日）は、Facebook.comの作り直しでアトミックなクラスによってCSSサイズが80%減ったと書いています。同社のコードベースでの値です。 同じ記事によれば、StyleXはFacebook・Instagram・WhatsApp・Messenger・Threadsで標準のスタイリングシステムになっており、社外ではFigmaとSnowflakeが採用しています。[npm Downloads API](https://api.npmjs.org/downloads/point/2026-10-04:2026-10-10/@stylexjs/stylex)で見た週間ダウンロード数（2026年10月4〜10日）は約194万回で、styled-components（約1,103万回）の6分の1程度です。 ### 0.19.1のコンパイラが実際に出力するCSS 挙動を確かめるため、`@stylexjs/babel-plugin` 0.19.1と`@babel/core`で次のコンポーネントをコンパイルしました（`dev: false`、`runtimeInjection: false`）。 ``` const styles = stylex.create({ base: { fontSize: 16, color: 'rgb(60,60,60)', padding: 8 }, button: { backgroundColor: { default: 'lightblue', ':hover': 'blue' }, width: { default: 800, '@media (max-width: 800px)': '100%' }, }, }); ``` JavaScript側の`styles`は、プロパティごとのキーにクラス名を対応させただけのオブジェクトに置き換わります（`base: { kGuDYH: "x1j61zf2", kMwMTN: "x10ipcqr", kmVPX3: "xe8ttls", $$css: true }`）。CSSは`processStylexRules`で1ファイルにまとめられ、`useLayers: true`を指定すると次の形になりました（後述の`highlighted`のルールは省略）。 ``` @layer priority1, priority2, priority3; @layer priority1{ .xe8ttls{padding:8px} } @layer priority2{ .x15neal0{background-color:lightblue} .x10ipcqr{color:rgb(60,60,60)} .x1j61zf2{font-size:16px} .xbrh7vm:hover{background-color:blue} } @layer priority3{ .xdpfuu1{width:800px} @media (max-width: 800px){.xkf749i.xkf749i{width:100%}} } ``` ショートハンドの`padding`は個別プロパティより低いレイヤーに置かれるので、`padding`と`paddingTop`を併用しても記述順に関係なく`paddingTop`が勝ちます。`useLayers`を省略した場合（[Babelプラグインの設定リファレンス](https://stylexjs.com/docs/api/configuration/babel-plugin)では既定値`false`）は`@layer`を使わず、`padding`は素の`.xe8ttls`、`color`は`.x10ipcqr:not(#\#)`、メディアクエリ付きの`width`は`:not(#\#)`を2つ重ねる、というように付ける数で同じ優先順位を表していました。レイヤー番号や重ねる数は、そのビルドに含まれるスタイル全体で使われた優先度に応じて振り直されます。`:not(#\#)`は1つでIDセレクタ1個分の詳細度を足すため、既存CSSのクラスセレクタよりStyleX側が勝ちやすくなります。既存のCSSと混ぜるなら`useLayers`を有効にし、レイヤーの順序で関係を決める方が管理しやすくなります。 ### 実行時CSS-in-JSとの構造的な違い Emotionや[styled-components](/tech/details/3048/)のような従来型のCSS-in-JSは、レンダリング中にスタイル文字列を組み立ててstyleタグをDOMに挿入します。Metaのブログは、この方式が「計測できるほどの性能上のオーバーヘッド」を持ち込んでいたと振り返っています。StyleXでは実行時に行うのはクラス名の結合だけで、その代わりスタイルの値は静的に解析できる形で書く必要があります（任意の関数の戻り値やオブジェクトのスプレッドは不可）。 ## StyleXのインストールとビルド設定 ### 正しいパッケージは@stylexjs/stylex（stylexは別物） ランタイムは`@stylexjs/stylex`です。npmでスコープなしの[stylex](https://www.npmjs.com/package/stylex)を引くと、説明文「Easily convert CSS styles between the DOM and Javascript, and back.」、メンテナーryanhefner、最新版0.3.0の別パッケージが出てきます。Metaのライブラリとは関係がないため、`npm install stylex`と書かれた手順は誤りです。 ``` npm install --save @stylexjs/stylex npm install --save-dev @stylexjs/babel-plugin @stylexjs/postcss-plugin postcss autoprefixer npm install --save-dev @stylexjs/eslint-plugin ``` ESLintプラグインは省きたくなりますが、[公式のインストール手順](https://stylexjs.com/docs/learn/installation)は「StyleXのコンパイラは寛容で、誤りを含むスタイルもコンパイルしてしまう」として導入を勧めています。ゼロから作るなら、0.18.0で入ったスキャフォールドCLI（`npm create @stylexjs my-app`）でテンプレートを選んで雛形を作れます。 ### 2024年以前の手順で使う@stylexjs/nextjs-pluginは非推奨 公開直後の解説記事の多くは、`@stylexjs/nextjs-plugin`で`next.config.js`を包む手順です。[CHANGELOG](https://github.com/facebook/stylex/blob/main/CHANGELOG.md)によると、このパッケージは0.12.0（npm公開2025年4月11日）で`@stylexjs/webpack-plugin`・`@stylexjs/esbuild-plugin`・`@stylexjs/dev-runtime`・`@stylexjs/open-props`とともに非推奨になりました。npmレジストリ上も最終版は0.11.1（2025年3月3日）で止まり、「Package no longer supported.」の非推奨表示が付いています。 旧記事の`genConditionalClasses`も0.13.0で`enableInlinedConditionalMerge`に改名されています。古い設定は写さず、次の節の構成で組み直してください。 ### Next.jsのBabel・PostCSSによる2段構成 現行の[Next.js向け手順](https://stylexjs.com/docs/learn/installation/nextjs)では、BabelプラグインがStyleX呼び出しを変換し、PostCSSプラグインが`@stylex`ディレクティブを生成済みCSSに置き換えます。 ``` // babel.config.js const path = require('path'); const dev = process.env.NODE_ENV !== 'production'; module.exports = { presets: ['next/babel'], plugins: [ ['@stylexjs/babel-plugin', { dev, runtimeInjection: false, enableInlinedConditionalMerge: true, treeshakeCompensation: true, aliases: { '@/*': [path.join(__dirname, '*')] }, unstable_moduleResolution: { type: 'commonJS' }, }], ], }; ``` ``` // postcss.config.js const babelConfig = require('./babel.config'); module.exports = { plugins: { '@stylexjs/postcss-plugin': { include: ['src/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}'], babelConfig: { babelrc: false, parserOpts: { plugins: ['typescript', 'jsx'] }, plugins: babelConfig.plugins, }, useCSSLayers: true, }, autoprefixer: {}, }, }; ``` ルートレイアウトで読み込むCSS（`app/globals.css`など）に`@stylex;`を1行だけ書くと、そこにアプリ全体分のCSSが出力されます。PostCSS側がBabel設定を読み込むのは両者の設定を一致させるためで、公式ドキュメントは「Next.js 16.0.3以降はWebpackとTurbopackの両方で動作する」としており、`next.config.js`の変更は要りません。 Babel設定を置いたときの影響はバンドラーで異なります。[Next.js Compilerのドキュメント](https://nextjs.org/docs/architecture/nextjs-compiler)のとおり、WebpackではRust製の[SWC](/tech/details/16019/)をやめてBabelで変換します。[Turbopackのドキュメント](https://nextjs.org/docs/app/api-reference/turbopack)によれば、Next.js 16以降のTurbopackは設定ファイルを検出するとBabelを自動で使いつつ、Next.js内部の変換と古いECMAScript向けの変換にはSWCを使い続けます（`node_modules`内のファイルはBabelの対象外）。どちらの場合も、大きなアプリではビルド時間を導入前後で測ってください。 ### Vite・Webpack・Rspackのunplugin設定 0.17.0（2025年11月）で`@stylexjs/unplugin`が入り、Vite・Webpack・Rspack・Rollupなどを1つのパッケージで扱えるようになりました。依存に`@babel/core`を含んでおり、Babelを内蔵しなくなった[@vitejs/plugin-react v6](/tech/details/2680/)と組み合わせても、StyleXの変換は自前で行います。 ``` npm install --save-dev @stylexjs/unplugin ``` ``` // vite.config.ts import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import stylex from '@stylexjs/unplugin'; export default defineConfig({ plugins: [ stylex.vite({ useCSSLayers: true }), react(), ], }); ``` [Vite + Reactの手順](https://stylexjs.com/docs/learn/installation/vite/vite-react)は、Fast Refreshを保つためにStyleXのプラグインを`@vitejs/plugin-react`より前に置くよう指示しています。`vite build`ではアプリのルートで読み込んだCSSファイルにStyleXの出力が追記されるので、CSSのリクエストは増えません。 ## StyleXの主要APIとスタイル記法 ### createとpropsによる定義と適用、後勝ちのマージ 中核は2つの関数です。`stylex.create`で名前付きのスタイルを定義し、`stylex.props`の戻り値を要素にスプレッドします。`className={styles.button}`のようにスタイルオブジェクトを直接渡す書き方はできません。 ``` import * as stylex from '@stylexjs/stylex'; const styles = stylex.create({ base: { fontSize: 16, color: 'rgb(60,60,60)', padding: 8 }, highlighted: { color: 'rebeccapurple' }, }); function Label({ isHighlighted }) { return StyleX; } ``` 同じプロパティが重なったら、`props`に後から渡した方が勝ちます。0.19.1のランタイムで実行すると、`props(base, highlighted)`の戻り値の`className`は`"x1j61zf2 xe8ttls x1n0khkq"`になり、`base`側のcolorクラス`x10ipcqr`はclass属性に残りませんでした。順序を入れ替えた`props(highlighted, base)`では`x10ipcqr`が残ります。CSS側の詳細度で競り合う前に、ランタイムがクラスを1つに絞っているわけです。`null`・`undefined`・`false`は無視されるため、`&&`や三項演算子で条件分岐を書けます。 ### 擬似クラス・メディアクエリのオブジェクト値記法 擬似クラスやメディアクエリは別のスタイルに分けず、プロパティの値をオブジェクトに置き換えて書きます。`default`キーが通常時の値です。 ``` const styles = stylex.create({ button: { backgroundColor: { default: 'lightblue', ':hover': 'blue', ':active': 'darkblue' }, width: { default: 800, '@media (max-width: 800px)': '100%' }, }, }); ``` 擬似要素は逆に、名前空間の直下に`'::placeholder': { color: '#999' }`のようなキーで書きます。[スタイル定義のドキュメント](https://stylexjs.com/docs/learn/styling-ui/defining-styles)は、CSSを小さく保つために`::before`と`::after`は避け、実際のHTML要素に置き換えるよう勧めています。 ### アロー関数とCSS変数による実行時の値の指定 実行時に決まる値は、名前空間をアロー関数として定義します。 ``` const styles = stylex.create({ dyn: (h) => ({ height: h }), });
``` 0.19.1でコンパイルすると、生成されるCSSは`.x16ye13r{height:var(--x-height)}`という固定のクラス1つと、`@property --x-height { syntax: "*"; inherits: false;}`だけでした。値そのものはインラインstyleの`--x-height`に入り、数値なら`120px`のように`px`を付けて渡されます。値の種類が何通りあってもCSSは増えない代わりに、要素ごとにstyle属性が付きます。 ### sxプロパティと@stylexjs/atomsのインライン指定 1か所でしか使わないスタイルに名前を付けるのが面倒なら、0.18.1で入った`sx`プロパティと、0.19.0で入った`@stylexjs/atoms`が使えます。`sx={...}`は`{...stylex.props(...)}`の短縮記法で、使えるのは`div`や`button`のような小文字のDOM要素だけです。 ``` import * as stylex from '@stylexjs/stylex'; import x from '@stylexjs/atoms';