MIT License

技术解读

以下内容由 GitRead 中文社区 编辑团队基于项目 README 与官方资料整理, 结合中文开发者的常见使用场景补充技术选型建议。具体以项目官方文档为准。

深度技术分析:macaron-css/macaron

项目背景与痛点

macaron 是一个类型安全的 CSS-in-JS 解决方案,它的设计理念在于通过编译器增强来达到零运行时开销,最大程度确保代码的安全性和生产力。在动态的 Web 开发中,CSS 与 JavaScript 集成往往会产生复杂性和难以追踪的问题,而 macaron 通过类型系统的支持,使得这些问题能够得到有效的解决。开发者无需关注运行时的性能开销,只需关注代码的类型安全性和可维护性。

技术核心揭秘

macaron 之所以能够实现零运行时开销及类型安全 CSS-in-JS,背后的原理在于编译器的增强。首先,它通过 TypeScript 的类型系统,使得 CSS 选择器、属性和值在编译时即可验证,这不仅减少了运行时错误,也增强了代码的健壮性。接着,macaron 利用 Babel 插件将 CSS-in-JS 代码转换为有效的 CSS 规则,并且经过编译后生成的文件只需包含必要的样式,没有任何额外的运行时框架。

macaron 技术架构分析

下面是 macaron 的技术架构图:

graph TD A[用户编写 CSS-in-JS 代码] --> B[TypeScript 编译器检查类型] B --> C[Babel 编译插件转换代码] C --> D[生成零运行时开销的 CSS 规则] D --> E[浏览器解析并应用样式]

在上图中,每一箭头代表了代码从编写到应用的各个阶段,其中特殊的 Babel 编译插件担当了重要角色,它将 TypeScript 转换为最终的样式代码,确保了零运行时开销。

功能亮点与差异

对比其他 CSS-in-JS 解决方案,macaron 的优势体现在几个方面:

  1. 类型安全:通过 TypeScript 的类型系统增强,它在编译时确保所有的样式定义都是类型安全的。
  2. 零运行时开销:不同于其他可能需要在浏览器中运行额外 JavaScript 代码的方案,macaron 编译后的 CSS 文件几乎不包含任何运行时逻辑。
  3. 最大提升生产力:更加简便的开发体验,以及集中的代码维护方式,极大程度地提高了开发者的效率和满意度。

应用场景与落地建议

在生产环境中使用 macaron 时需要注意以下几点:

  • 引入足够的依赖:项目中需要引入对应的 TypeScript 和 Babel 插件来进行编译。
  • 类型定义文件:要为项目编写和维护类型定义文件,确保所有 CSS 样式在编译时都能够正确定义和检查。
  • 跨浏览器一致性:虽然 macaron 本身处理了大部分一致性的需求,但在特定浏览器中的兼容性需求仍需开发者自身有所了解。

macaron 特别适合那些注重团队开发效率,希望减少运行时性能损失,且能够接受类型系统严格验证这一开发流派的项目。对于追求高质量前端开发实践的团队来说,使用 macaron 显得尤为重要。

综合评价

macaron 无疑为 CSS-in-JS 提供了一种全新的思路,立足于类型安全性和零运行时开销,它通过一系列编译时的优化,极大程度上提升了开发者的生产力。不过,它的优势与限制也十分明显,对于那些不愿意在开发流程中使用类型系统或者希望尽量减少编译步骤的团队而言,macaron 可能未必是最优选择。总体来说,macaron 非常适合现代前端团队,特别是那些使用 TypeScript 开发并追求类型安全和高性能的开发团队。

关于

GitHub 原始描述(英文)

Compiler-augmented typesafe CSS-in-JS with zero runtime, colocation, maximum safety and productivity

描述取自 GitHub 官方 API,保持仓库作者书写的原文。

简要分析

热度分
833
价值分
477
活跃状态
活跃

语言占比

JavaScript
MDX
TypeScript

Release

README

CSS-in-JS with zero runtime, type safety and colocation

Features

  • Zero runtime bundles with build time style extraction.
  • Colocation of styles and components.
  • First class Typescript support.
  • Supports both styled-components API and vanilla styling API.
  • Stitches-like variants API.
  • Out of box support for React, Solid and Qwik.
  • Integrations for esbuild and Vite.

Documentation

For full documentation, visit https://macaron.js.org

Example

Styled API

// or import it from @macaron-css/solid
import { styled } from '@macaron-css/react';

const Button = styled('button', {
  base: {
    borderRadius: 6,
  },
  variants: {
    color: {
      neutral: { background: 'whitesmoke' },
      brand: { background: 'blueviolet' },
      accent: { background: 'slateblue' },
    },
    size: {
      small: { padding: 12 },
      medium: { padding: 16 },
      large: { padding: 24 },
    },
    rounded: {
      true: { borderRadius: 999 },
    },
  },
  compoundVariants: [
    {
      variants: {
        color: 'neutral',
        size: 'large',
      },
      style: {
        background: 'ghostwhite',
      },
    },
  ],

  defaultVariants: {
    color: 'accent',
    size: 'medium',
  },
});

// Use it like a regular solidjs/react component
function App() {
  return (
    <Button color="accent" size="small" rounded>
      Click me!
    </Button>
  );
}

Styling API

The styling API is the same api is vanilla-extract, but allows styles to be defined in the same file, improving the DX.

Check out vanilla-extract docs for the API reference.

These functions can also be called directly inside expressions to provide a css prop-like API with zero-runtime cost:-

import { style } from '@macaron-css/core';

function App() {
  return (
    <div
      class={style({
        display: 'flex',
        padding: '10px',
      })}
    >
      <button class={style({ color: 'red' })}>Click me</button>
    </div>
  );
}

Playground

You can try about these above examples at https://macaron.js.org/playground and see how macaron figures out which expressions have to be extracted and what your code would look like after being transpiled

How it works

https://macaron.js.org/docs/working/

Acknowledgements

  • Vanilla Extract Thanks to the vanilla-extract team for their work on VE, which macaron uses for evaluating files.

  • Dax Raad Thanks to Dax for helping me with this and thoroughly testing it outß, helping me find numerous bugs and improving macaron.

评论

暂无评论