Vanilla Extract 迁移指南：从 treat 到现代 CSS 开发

Vanilla Extract 迁移指南：从 treat 到现代 CSS 开发

vanilla-extract Zero-runtime Stylesheets-in-TypeScript 项目地址: https://gitcode.com/gh_mirrors/va/vanilla-extract

前言

在 CSS-in-JS 领域，treat 曾经是一个备受欢迎的解决方案，而如今 Vanilla Extract 作为它的进化版本，提供了更现代化、更符合 CSS 标准的工作流程。本文将详细介绍如何从 treat 迁移到 Vanilla Extract，帮助开发者顺利完成技术栈升级。

迁移基础准备

文件扩展名变更

最直观的变化是文件扩展名的调整：

• 旧格式：*.treat.ts
• 新格式：*.css.ts

这种变化更清晰地表明了文件的用途——生成 CSS 样式。

文件间相互引用

Vanilla Extract 解决了 treat 的一个重要限制：现在 .css.ts 文件可以相互引用了。这意味着你可以更好地组织样式代码，无需再为文件间的依赖关系而烦恼。

构建配置调整

Webpack 配置变化

与 treat 自动处理 CSS 不同，Vanilla Extract 采用了更轻量级的方案：

1. 生成标准的全局 CSS 文件
2. 需要开发者自行配置 webpack 处理这些 CSS 文件

这种变化带来了更大的灵活性，你可以根据需要配置各种 CSS 处理工具。

Autoprefixer 处理

Vanilla Extract 不再内置 Autoprefixer，需要手动添加到 webpack 配置中。这实际上给了开发者更多选择权，比如你可以选择使用 postcss-preset-env 来获得更多现代化 CSS 特性支持。

URL 资源处理

对于 *.vanilla.css 文件，建议禁用 css-loader 的 URL 处理功能，保持与 treat 一致的资源引用方式（通过 JavaScript import 而非 CSS url()）。示例配置：

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        oneOf: [
          {
            test: /\.vanilla\.css$/i,
            use: [
              MiniCssExtractPlugin.loader,
              {
                loader: 'css-loader',
                options: { url: false }
              }
            ]
          },
          {
            use: [MiniCssExtractPlugin.loader, 'css-loader']
          }
        ]
      }
    ]
  },
  plugins: [
    new VanillaExtractPlugin(),
    new MiniCssExtractPlugin()
  ]
};

主题系统迁移

创建主题

Vanilla Extract 提供了两种创建主题的方式：

1. 全局主题（适合单一主题场景）：

import { createGlobalTheme } from '@vanilla-extract/css';

export const vars = createGlobalTheme(':root', {
  color: {
    primary: 'blue',
    secondary: 'green'
  },
  spacing: {
    small: '8px',
    medium: '16px'
  }
});

2. 多主题支持：

import { createTheme } from '@vanilla-extract/css';

export const [lightTheme, vars] = createTheme({
  color: {
    background: 'white',
    text: 'black'
  }
});

export const darkTheme = createTheme(vars, {
  color: {
    background: 'black',
    text: 'white'
  }
});

主题值必须是字符串

Vanilla Extract 要求所有主题值必须是字符串，这确保了 CSS 变量的正确性：

const themeClass = createGlobalTheme(':root', {
  spacing: {
    small: '8px',  // 必须明确单位
    large: '24px'
  },
  fontWeight: {
    bold: '700'    // 无单位值也需要字符串形式
  }
});

React 集成变化

替换 TreatProvider

Vanilla Extract 使用标准的 CSS 变量实现主题，不再需要 React 上下文。只需将主题类名应用到元素上：

import { themeClass } from './vars.css';

export const App = () => (
  <div className={themeClass}>
    {/* 应用内容 */}
  </div>
);

处理 React Portals

对于使用 React Portals 的场景，需要手动传递主题类名：

import { useVanillaTheme } from './VanillaThemeContext';

export const Modal = () => {
  const themeClass = useVanillaTheme();
  
  return createPortal(
    <div className={themeClass}>
      {/* 模态框内容 */}
    </div>,
    document.body
  );
};

样式定义变化

简化样式引用

不再需要 useStyles 和 styleRefs，直接导入样式即可：

import * as styles from './styles.css';

export const Component = () => (
  <div className={styles.root}>
    {/* 组件内容 */}
  </div>
);

样式计算处理

CSS 变量的计算需要使用 CSS 的 calc 函数：

import { calc } from '@vanilla-extract/css-utils';
import { vars } from '../vars.css';

const negativeMargin = style({
  marginTop: calc.negate(vars.spacing.medium)
});

对于复杂计算（如颜色处理），建议将计算结果预先定义在主题中：

// vars.css.ts
import { lighten } from 'polished';

export const vars = createGlobalTheme(':root', {
  color: {
    primary: 'blue',
    primaryLight: lighten(0.2, 'blue')
  }
});

高级功能迁移

替换 styleMap

使用 styleVariants 替代 styleMap：

import { styleVariants } from '@vanilla-extract/css';

export const variantStyles = styleVariants({
  primary: { color: vars.color.primary },
  secondary: { color: vars.color.secondary }
});

动画处理

动画定义现在需要单独使用 keyframes 函数：

import { keyframes, style } from '@vanilla-extract/css';

const fadeIn = keyframes({
  '0%': { opacity: 0 },
  '100%': { opacity: 1 }
});

const animatedElement = style({
  animation: `${fadeIn} 1s ease-in`
});

迁移策略建议

1. 渐进式迁移：Vanilla Extract 和 treat 可以在同一项目中并存，建议逐步迁移
2. 优先处理主题系统：先迁移主题定义，再处理组件样式
3. 利用类型系统：Vanilla Extract 提供了优秀的类型支持，迁移时注意类型定义
4. 团队协作：建立迁移规范，确保团队成员遵循一致的迁移方式

总结

从 treat 迁移到 Vanilla Extract 不仅是工具的改变，更是思维方式的转变——从 JavaScript 驱动的样式系统转向更符合标准的 CSS 变量方案。这种转变虽然需要一些适应，但最终会带来更可预测、更高效的样式开发体验。通过本文的指南，希望你能顺利完成迁移，享受 Vanilla Extract 带来的现代化 CSS 开发体验。

vanilla-extract Zero-runtime Stylesheets-in-TypeScript 项目地址: https://gitcode.com/gh_mirrors/va/vanilla-extract