Astral UI 类CLI

一个用于安装和管理 Astral UI 组件在任意代码库中的命令行工具.

使用量

对于大多数项目,我们建议使用CLI与 npx 或者说 yarn dlx 而不是在全球安装:

# Using npx
npx @cloudwick/astral-ui-cli init

# Using yarn
yarn dlx @cloudwick/astral-ui-cli init

如果您在工作流程中频繁使用 CLI, 您可以在全球安装 :

# Install globally with npm (only if needed)
npm install -g @cloudwick/astral-ui-cli

# Install globally with yarn (only if needed)
yarn global add @cloudwick/astral-ui-cli

快速启动

# Initialize your project
npx @cloudwick/astral-ui-cli init

# Add components
npx @cloudwick/astral-ui-cli add button card

# Start using in your code
import { Button } from '@components/button';
import { cn } from '@utils';
import { keyboardKeys, mobileBreakPoint } from '@constants';
import { useWindowSize } from '@hooks';

工作流程

最好的经验是,遵循这些步骤,以便:

1. 初始化 您的项目与 npx @cloudwick/astral-ui-cli init - 这将显示您工程类型的路径化名设置指令
2. 配置路径别名 在工程中遵循初始化时显示的指令
3. 添加组件 与 npx @cloudwick/astral-ui-cli add [component...]
4. 修复尾风 如果需要的话 npx @cloudwick/astral-ui-cli repair-tailwind
5. 进口和使用 应用程序中的组件

图标

init

以 Astral Core 配置初始化项目 .

npx @cloudwick/astral-ui-cli init

此命令将 :

• 创建一个 components.json 配置文件
• 建立必要的依赖关系
• 如果还没有安装尾风 CSS
• 在现有 Tailwind 配置中添加所需的配置或创建新配置
• 添加工具函数
• 为一致的打字法添加Noto Sans字体文件
• 为适当的字体渲染设置字体 CSS
• 根据您的工程类型( Next.js, Vite, Webpack, CRA等) 显示详细的路径别名设置指令

选项

说明: 当文件已经存在时,在替换之前会自动创建备份.

Init 命令自动检测您的工程类型,并提供特定路径别名配置指令,用于:

• 下一个.js:别名使用tsconfig.json/jsconfig.json
• 维特: 提供 vite.config.js/ts 配置
• 网络软件包: 提供webpack.config.js配置
• 创建反应应用提供 CRACO 设置指令
• 常规: 为其他项目类型提供基础配置

此外,CLI还检测了tsconfig.app.json(被一些框架用于特定应用程序的TypeScript设置)并提供了配置指南.

add

在您的工程中添加组件 .

npx @cloudwick/astral-ui-cli add [component...]

选项

说明: 当一个组件已经存在时, 在替换之前会提示您 。 替换时自动创建备份 .

实例

# List all available components
npx @cloudwick/astral-ui-cli add --list

# List components in silent mode (component names only)
npx @cloudwick/astral-ui-cli add --list --silent

# Add specific components
npx @cloudwick/astral-ui-cli add button card select

# Add all components
npx @cloudwick/astral-ui-cli add --all

# Add a component to a specific directory
npx @cloudwick/astral-ui-cli add button --path ./components/custom

# Skip installing internal component dependencies
npx @cloudwick/astral-ui-cli add button --skip-dependencies

repair-tailwind

设置失败时修复 Tailwind 配置 - 仅在遇到 Tailwind 问题时使用 .

npx @cloudwick/astral-ui-cli repair-tailwind

此命令将 :

• 检查已有的 Tailwind 配置并创建时间标记的备份
• 为您的工程创建新的带有相应文件扩展名的 Tailwind 配置
• 建立完整的CSS结构,包括:
  • 主要 CSS 文件, 包含适当的导入
  • 字体样式表( fonts.min.css)
• 确保安装适当的依赖性
• 在修改前创建已存在的 Tailwind 配置的备份

创建的 CSS 结构将完全符合 init 命令创建,包括:

• 颜色和主题的 CSS 变量
• 字体导入和配置
• 适当的文件组织

选项

说明: 该命令在替换已存在的文件并自动创建备份前会提示.

示例使用

# Basic repair
npx @cloudwick/astral-ui-cli repair-tailwind

# Repair in a specific directory
npx @cloudwick/astral-ui-cli repair-tailwind --cwd ./my-project

配置

组件.json

这个 components.json 文件在初始化时创建, 并包含您的项目的配置 :

{
  "$schema": "./schema/components-config.schema.json",
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/styles/globals.css",
  },
  "aliases": {
    "components": "src/components",
    "utils": "src/utils",
    "constants": "src/constants",
    "hooks": "src/hooks"
  }
}

您可以编辑此文件以自定义 :

• 尾风. 配置: 您的 Tailwind 配置文件路径
• 密码: 您全局 CSS 文件的路径
• 别名: 安装组件、公用设施、常数和钩子的路径

说明编号: utils 路径在 components.json 在没有文件扩展名的情况下存储。 CLI 自动添加 .ts 或者说 .js 基于您项目是否使用 TypeScript 或 JavaScript 的扩展。 在配置路径别名时,您应当使用路径,而无需显示扩展名 components.json 文档.

JSON Schema 组件

和你的一样 components.json, CLI 生成一个 JSON Schema 文件 schema/components-config.schema.json。 。 。 . 您可以在编辑器或 CI 中使用这个方案来验证您的配置 。 它定义:

• $schema (字符串):这个计划文件的URI.
• tailwind (对象):您 Tailwind 配置的路径( )config)和 CSS 文件 (css) (中文(简体) ).
• aliases (对象):用于 components, (中文(简体) ), utils, (中文(简体) ), constants,以及 hooks编辑 hooks 条目是可选的 —— 由更古老的 CLI 版本所创建的配置省略并返回到 src/hooks (单位:千美元)lib/hooks 下册.

详情见 schema/components-config.schema.json 在你的项目.

可用组件

要看到所有可用组件的完整列表, 请运行 :

npx @cloudwick/astral-ui-cli add --list

这将显示所有组件及其描述 。 您也可以使用无声模式获取组件名称 :

npx @cloudwick/astral-ui-cli add --list --silent

大众成分

使用组件

添加组件后,您可以在应用程序中导入和使用:

反应/下一步js 示例

import { Button } from '@components/button';
import { Card, CardHeader, CardContent } from '@components/card';
import { cn } from '@utils';
import { keyboardKeys, mobileBreakPoint } from '@constants';

export function MyComponent() {
  return (
    <Card>
      <CardHeader>My Card</CardHeader>
      <CardContent>
        <p>Card content goes here</p>
        <Button 
          className={cn("mt-4", "custom-class")}
          variant="outline"
        >
          Click Me
        </Button>
      </CardContent>
    </Card>
  );
}

关于 Utils 文件

CLI 创建工具文件 cn 帮助结合 Tailwind 类的函数。 此文件 :

• 是在路径中指定的初始化过程中自动创建的 components.json (单位:千美元)utils 字段)
• 拥有相应的文件扩展名( N).ts 用于类型脚本项目, .js 为 JavaScript 项目自动添加)
• 应在组件中导入为 import { cn } from '@utils' 设置路径别名后

这个 cn 函数允许您有条件地合并类名并自动处理 Tailwind 类冲突.

关于虎克目录

CLI还安装了共享反应钩的目录(useAsyncOptions, (中文(简体) ), useFilterQuery, (中文(简体) ), useInfiniteScroll, (中文(简体) ), useListboxKeyboardNav, (中文(简体) ), useIsTruncated, (中文(简体) ), useWindowSize页:1 此目录 :

• 是在路径中指定的初始化过程中自动创建的 components.json (单位:千美元)hooks 字段)
• 暴露通过 @hooks 化名,必须同时配置 @components, (中文(简体) ), @utils,以及 @constants
• 是由几个组成部分要求的—— Select, (中文(简体) ), TransferList, (中文(简体) ), MultiSelectTransfer, (中文(简体) ), Scrollbar,以及 CtaGroup 全部导入自 @hooks,所以这些组件如果没有这个化名将无法解决

导入钩子为 import { useWindowSize } from '@hooks' 总是从枪管,而不是从个人文件.

样式组件

登记册中的组件需要 Tailwind CSS 在您的应用程序中进行适当的配置 。 当你跑的时候 npx @cloudwick/astral-ui-cli init国家行动倡议将:

1. 检查已有的 Tailwind 配置并升级到必要的设置
2. 创建一个 CSS 文件, 包含组件样式所需的 CSS 变量
3. 生成一个 STYLING. md 文件, 包含关于样式系统的文档

尾风集成

CLI 智能地处理现有的 Tailwind 配置 :

• 自动检测带有任何扩展名的现有配置文件(.js,.ts,.mjs,.cjs)
• 创建任何已存在的 Tailwind 配置文件的时间戳备份
• 根据您的工程类型创建新的尾风. config 文件并附带适当的扩展名 :
  • 类型脚本项目 : .ts 扩展
  • 无害环境管理项目: .mjs 扩展
  • 普通JS项目: .js 扩展
  • 无害环境管理包中常见的JS(有"类型":"模块"): .cjs 扩展
• 保存您的工程语言( TypeScript 或 JavaScript) 和模块系统( ESM 或 CommunityJS)

配置中包含必要的尾风特性 :

• 有 RGB 变量的颜色系统,用于初级、二级、成功、警告、出错和灰色平面
• 自定义卡片组件的框阴影
• 暗模式支持( 主题拖动的“ 类” 模式)

CSS 变量

CSS文件包括所有必要的CSS变量,这些变量构成参考内容,包括:

• 基本颜色(初级、二级等)
• 状态颜色( 成功、 错误、 警告)
• 光/暗模式的主题变量

解决问题

别名问题

如果你对进口有问题:

1. 检查您的配置: 确保 tsconfig.json/jsconfig.json中的路径与您的工程结构相匹配. 所有四个别名都需要: @components/*, (中文(简体) ), @utils, (中文(简体) ), @constants,以及 @hooksA级 Cannot find module '@hooks' 错误表示缺少别名 .
2. 二. 具体框架问题数字 :
   • 下一个.js: 确保您正在使用正确的导入格式用于您的 Next.js 版本
   • tsconfig.app.json (英语): 如果您的工程使用 tsconfig.app.json , 请配置此路径
   • 创建反应应用: 您需要 CRACO 或类似的路径名才能启用
3. 校验设置: 路径别名设置指令显示在 init - 你可以跑开 npx @cloudwick/astral-ui-cli init {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}再次见到他们
4. 检查组件. json: 确保“别名”部分中的路径与您的工程结构相匹配

造型问题

如果组件的样式不正确:

1. 确保 Tailwind CSS 配置在您的应用程序中正确加载
2. 校验 CSS 变量包含在您的 CSS 主文件中
3. 检查您的组件是否正在正确导入所需的公用事业
4. 运行 npx @cloudwick/astral-ui-cli repair-tailwind 创建新的尾风配置
5. 如果您需要将新配置与您现有的定制合并, 请使用您的备份文件作为参考

捐款

关于发展和促进国家行动倡议的资料,请参见: 捐款额 在寄存器根中的文件.

许可证

麻省理工学院