Skip to content
BranchesTags

Repository files navigation

jc-stack-abp

中文版 | English

中文版

概述

jc-stack-abp 是一个围绕 ABP 协议构建的 monorepo，拆分出协议、客户端、初始化器与辅助工具，帮助前端项目在不同运行时中复用 ABP 相关能力。

主要包

包名 描述
@jcoder-labs/abp 统一入口：ABP + Next.js 集成（auth、permissions、navigation、signalr、i18n 的聚合包）
@jcoder-labs/infra 基础设施：统一错误处理与日志抽象
@jcoder-labs/auth 认证抽象接口（AuthProvider、AuthSession、AuthToken）
@jcoder-labs/abp-core 协议核心：DTO/类型、stale-while-revalidate 缓存与策略判断
@jcoder-labs/abp-client Fetch 封装 (含请求去重、重试、超时) + Orval 生成的 API endpoints/models
@jcoder-labs/abp-bff Backend-for-frontend 代理工具 (含响应缓存、限流)
@jcoder-labs/service-client 多服务上下文管理、BFF/Upstream 路由、健康检查
@jcoder-labs/permissions 框架无关的权限策略引擎 (含 React hooks)
@jcoder-labs/signalr SignalR 客户端 (含连接池 + React hooks)
@jcoder-labs/i18n 国际化工具（封装 next-intl）
@jcoder-labs/api-tooling Orval preset 与 CLI，OpenAPI → SWR/React Query + Zod
@jcoder-labs/cli CLI 工具：jc-stack init 项目初始化、jc-api gen API 代码生成

分层架构

┌─────────────────────────────────────────────────────────┐
│  应用层 (Your App)                                       │
├─────────────────────────────────────────────────────────┤
│  统一入口 (abp) — 聚合 auth/permissions/navigation/i18n  │
├─────────────────────────────────────────────────────────┤
│  集成层 (abp-bff)                                        │
├─────────────────────────────────────────────────────────┤
│  客户端层 (abp-client, permissions, service-client)      │
├─────────────────────────────────────────────────────────┤
│  协议层 (abp-core, auth)                                 │
├─────────────────────────────────────────────────────────┤
│  基础设施层 (infra)                                       │
├─────────────────────────────────────────────────────────┤
│  辅助层 (signalr, i18n)  |  工具层 (api-tooling, cli)     │
└─────────────────────────────────────────────────────────┘

v0.1.0+ 架构优化: 采用服务端优先模式，移除 AbpProvider，权限检查在服务端完成后通过 Props 传递给客户端。客户端 Bundle 从 ~600KB 降至 ~10KB。

环境变量约定

所有包统一使用以下环境变量命名约定：

服务 URL

服务 Server-only (推荐) Client-safe 兼容格式 (已废弃)
ABP JC_ABP_API_URL NEXT_PUBLIC_JC_ABP_API_URL ABP_API_BASE_URL
MES JC_MES_API_URL NEXT_PUBLIC_JC_MES_API_URL MES_API_BASE_URL
SRM JC_SRM_API_URL NEXT_PUBLIC_JC_SRM_API_URL SRM_API_BASE_URL

注意: *_API_BASE_URL 格式已废弃,请使用 JC_*_API_URL 格式。旧格式仍作为回退支持。

应用配置

变量 描述
NEXT_PUBLIC_APP_URL 应用基础 URL
ABP_FETCH_SERVER_MODE 服务端路由模式 (upstream / bff)

认证配置

变量 描述
AUTH_SECRET Better Auth 密钥
BETTER_AUTH_COOKIE_PREFIX Cookie 前缀
OAUTH_CLIENT_ID OAuth 客户端 ID
OAUTH_CLIENT_SECRET OAuth 客户端密钥
OAUTH_ISSUER OAuth 发行者 URL
OAUTH_SCOPES OAuth 作用域

快速上手

10 分钟快速集成？ 查看 快速开始指南

新项目初始化？ 请查看 项目初始化指南 获取完整的从零开始教程。

开发 jc-stack-abp 本身？ 请查看 贡献指南

# 安装依赖
bun install

# 类型检查和构建
bun run build

# 运行测试
bun run test

# 代码格式化
bun run format

# 代码检查
bun run lint

示例 .env.local

# 应用 URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# 服务 URL (Server-only)
JC_ABP_API_URL=https://localhost:44380
JC_MES_API_URL=https://localhost:44381
JC_SRM_API_URL=https://localhost:44301

# 认证
AUTH_SECRET=your-secret-key
BETTER_AUTH_COOKIE_PREFIX=myapp

# OAuth
OAUTH_CLIENT_ID=MyApp_Web
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_ISSUER=https://localhost:44380
OAUTH_SCOPES=openid profile email offline_access

English

Overview

jc-stack-abp is a protocol-first workspace that isolates ABP DTOs, fetch clients, scaffolding helpers, and generation tooling into purpose-built packages.

Core Packages

Package Description
@jcoder-labs/abp Unified entry — ABP + Next.js integration (aggregates auth, permissions, navigation, signalr, i18n)
@jcoder-labs/infra Infrastructure: Unified error handling & logging abstractions
@jcoder-labs/auth Authentication abstractions (AuthProvider, AuthSession, AuthToken)
@jcoder-labs/abp-core Protocol primitives: DTOs, stale-while-revalidate cache, policies
@jcoder-labs/abp-client Fetch wrapper (with request dedup, retry, timeout) + Orval-generated API endpoints/models
@jcoder-labs/abp-bff Backend-for-frontend proxy utilities (with response caching, rate limiting)
@jcoder-labs/service-client Multi-service context, BFF/Upstream routing, health checks
@jcoder-labs/permissions Framework-agnostic permission policy engine (with React hooks)
@jcoder-labs/signalr SignalR client (with connection pooling + React hooks)
@jcoder-labs/i18n Internationalization utilities (wraps next-intl)
@jcoder-labs/api-tooling Orval preset & CLI: OpenAPI → SWR/React Query + Zod
@jcoder-labs/cli CLI tools: jc-stack init project scaffolding, jc-api gen API code generation

Layered Architecture

┌─────────────────────────────────────────────────────────┐
│  Application Layer (Your App)                            │
├─────────────────────────────────────────────────────────┤
│  Unified Entry (abp) — aggregates auth/permissions/etc.  │
├─────────────────────────────────────────────────────────┤
│  Integration Layer (abp-bff)                             │
├─────────────────────────────────────────────────────────┤
│  Client Layer (abp-client, permissions, service-client)  │
├─────────────────────────────────────────────────────────┤
│  Protocol Layer (abp-core, auth)                         │
├─────────────────────────────────────────────────────────┤
│  Infrastructure Layer (infra)                            │
├─────────────────────────────────────────────────────────┤
│  Auxiliary (signalr, i18n)  |  Tooling (api-tooling, cli)│
└─────────────────────────────────────────────────────────┘

v0.1.0+ Architecture Optimization: Adopts server-first approach, removes AbpProvider, permission checks done on server and passed via Props to client. Client bundle reduced from ~600KB to ~10KB.

Environment Variable Convention

All packages use unified environment variable naming:

Service URLs

Service Server-only (Recommended) Client-safe Legacy Format (Deprecated)
ABP JC_ABP_API_URL NEXT_PUBLIC_JC_ABP_API_URL ABP_API_BASE_URL
MES JC_MES_API_URL NEXT_PUBLIC_JC_MES_API_URL MES_API_BASE_URL
SRM JC_SRM_API_URL NEXT_PUBLIC_JC_SRM_API_URL SRM_API_BASE_URL

Note: The *_API_BASE_URL format is deprecated. Use JC_*_API_URL instead. Legacy format is still supported as fallback.

Application Config

Variable Description
NEXT_PUBLIC_APP_URL Application base URL
ABP_FETCH_SERVER_MODE Server routing mode (upstream / bff)

Authentication Config

Variable Description
AUTH_SECRET Better Auth secret
BETTER_AUTH_COOKIE_PREFIX Cookie prefix
OAUTH_CLIENT_ID OAuth client ID
OAUTH_CLIENT_SECRET OAuth client secret
OAUTH_ISSUER OAuth issuer URL
OAUTH_SCOPES OAuth scopes

Quick Start

10-minute integration? See the Quick Start Guide

New project setup? See the Project Setup Guide for a complete step-by-step tutorial.

Contributing to jc-stack-abp? See the Contributing Guide

# Install dependencies
bun install

# Type check and build
bun run build

# Run tests
bun run test

# Format code
bun run format

# Lint code
bun run lint

Example .env.local

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Service URLs (Server-only)
JC_ABP_API_URL=https://localhost:44380
JC_MES_API_URL=https://localhost:44381
JC_SRM_API_URL=https://localhost:44301

# Auth
AUTH_SECRET=your-secret-key
BETTER_AUTH_COOKIE_PREFIX=myapp

# OAuth
OAUTH_CLIENT_ID=MyApp_Web
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_ISSUER=https://localhost:44380
OAUTH_SCOPES=openid profile email offline_access

更新日志 / Changelog

查看 CHANGELOG.md 了解版本变更和迁移指南。

See CHANGELOG.md for version changes and migration guide.

文档 / Documentation

使用者文档 / User Documentation

开发者文档 / Developer Documentation

详细设计请参阅 docs/ARCHITECTURE.md。

For detailed design, see docs/ARCHITECTURE.md.

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages