Skip to content

v0.1.0

Choose a tag to compare

View all tags
@jcoder-stack jcoder-stack released this 02 Aug 06:45
· 54 commits to main since this release
v0.1.0
63235c3

ABP React Start 的第一个版本。给 ABP 后端配一套现代 React 前端：OIDC 登录经 BFF 代理、加密 cookie 会话、权限、多租户、本地化，以及一组直接读 ABP 协议的 CRUD 原语。

一条命令落地一个能跑的应用，然后它就退场——给你的是源码，不是运行时依赖。UI 全在你自己的仓库里，改它不需要绕过任何抽象。

装什么

npx @tanstack/cli create my-app && cd my-app

bun add @jcoder-stack/abp-react
bun add -D @jcoder-stack/cli @jcoder-stack/registry

npx jc-abp init
# 改 .env 与 abp.api.config.ts 指向你的后端
npx jc-abp gen && bun run dev

jc-abp init 会播种基线配置与主题、落认证外壳、按依赖序装齐 13 个块、接好 __root.tsx 与 router.tsx、生成路由树。装完是 85 个源码文件在你的 src/ 下。

三个包

包 作用
@jcoder-stack/abp-react 运行时内核。子路径导出 core / auth / proxy / react / router / permissions / i18n / logger
@jcoder-stack/cli jc-abp init / add / gen（命令名不带 scope）
@jcoder-stack/registry 13 个 shadcn 块与认证外壳的 copy-in 源，装成 devDependency

块：abp-layout、abp-login、app-shell、data-table、form、combobox、date-picker、tree、abp-crud、abp-table、abp-sheet、abp-permission-sheet、admin-pages（用户 / 角色 / 租户 / 设置 / 个人资料五页）。

装一个块会把它的前置块一并带上，不必自己排顺序。

前置

  • Node ≥ 18（gen 读 .ts 配置需要 Bun 或 Node ≥ 22.18）
  • bun 或 npm。npmrc 里配了 allow-scripts 时请用 bun：npx 会把它注入子进程，npm 拒绝项目级安装，shadcn 装块依赖必然失败。init 检测到这种情况会拒绝开工并说明原因
  • 一个 ABP 后端。gen 读它的 swagger 生成 API 客户端
  • peer：@tanstack/react-router ^1.170.18、react ^18 || ^19、zod ^4

外部 CLI 锁在已验证的 minor：shadcn@4.13、@tanstack/router-cli@1.167。

已知约束

@tanstack/react-table 用的是 9.0.0-beta.59。 data-table 块依赖 v9 才有的 tableFeatures / rowSortingFeature 等 API，块里已钉死这个版本。v9 正式发布前，升级它会编译失败。

@jcoder-stack/registry 必须装在项目根。 块之间用 ./node_modules/@jcoder-stack/registry/public/r/*.json 互相引用，这条路径按消费项目的根解析。npm 与 yarn classic 的 workspace 会把它提升到 workspace 根，成员目录下就找不到——那种项目请按依赖表自己排序逐块装。jc-abp init 不受影响，它自己解析真实路径。bun 与 pnpm 会在成员目录建符号链接，无此问题。

CRUD 相关的块要先跑 jc-abp gen。 abp-crud / abp-table / abp-sheet / abp-permission-sheet / admin-pages 都 import @/api/*，那是 gen 的产物。装完不跑 gen，编译不过。

本地后端用自签证书时 gen 会报 fetch failed。 Node 不读系统钥匙串，证书在钥匙串里受信也没用。加 NODE_TLS_REJECT_UNAUTHORIZED=0 即可。

.env.example 里的 AUTH_CLIENT_ID 与 AUTH_ISSUER 是占位。 client 必须是你后端 OpenIddict 里已注册的那一个，回调地址也要登记在它名下；scope 里还要带后端的 API 资源 scope，漏了登录能过但每个管理页都是空的。.env.example 的注释里给了探测方法。

权限名显示成原始 key 是后端的本地化缺口。 权限树用的是后端返回的 displayName，ABP 查不到词条就原样返回 key。补你后端对应资源的本地化文件即可。

安全

会话密封、OIDC 握手、BFF 代理是本项目自己承担的部分，漏洞请走 GitHub 的私密报告（Security → Report a vulnerability），不要开公开 issue。权限助手只管界面显隐，真正的授权在 ABP——前端能被绕过是设计如此。详见 SECURITY.md。

文档

从零初始化 · 按需装块 · 列表页与 CRUD · 表单四层 · 架构

参照应用 examples/starter 就是这套流程的产物，由脚本重放「脚手架 → 装包 → init → gen」得到，既是活文档也是端到端回归。

Assets 2
Loading