Skip to content

Commit 4f687e7

Browse files
SmilefounderSmilefounder
committed
chore: initialize pnpm workspace and add base TypeScript configuration
0 parents  commit 4f687e7

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+9060
-0
lines changed

‎.eslintrc.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
module.exports = {
2+
root: true,
3+
extends: [
4+
'eslint:recommended',
5+
'plugin:@typescript-eslint/recommended'
6+
],
7+
parser: '@typescript-eslint/parser',
8+
plugins: ['@typescript-eslint'],
9+
ignorePatterns: ['dist/', 'node_modules/'],
10+
rules: {
11+
// Add project-specific rules here
12+
}
13+
};

‎.github/prompts/MIGRATION_SPEC.prompt.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
mode: agent
3+
---
4+
5+
# Mixcore JavaScript SDK Extraction & Modularization Specification
6+
7+
## Objective
8+
9+
Extract all "shared", "base", and "apis" JavaScript/TypeScript code from `@mixcore/mix.spa.portal` and refactor them into a new, independent, and future-proof SDK repository: `mixcore/javascript-sdk`. The SDK must be modular, highly reusable, and suitable for internal, external, and third-party consumers (web, Node.js, microfrontends, plugins, etc.).
10+
11+
---
12+
13+
## Directory Structure & Tooling
14+
15+
- Use a monorepo structure with [Nx](https://nx.dev/), [Lerna](https://lerna.js.org/), or [Yarn Workspaces] if multiple packages are expected; otherwise, organize under `src/`.
16+
- Proposed directory structure:
17+
```
18+
mixcore/javascript-sdk/
19+
├── packages/
20+
│ ├── shared/ # Utilities, helpers, constants
21+
│ ├── base/ # Base classes, abstract models, interfaces
22+
│ └── apis/ # API clients, endpoint wrappers, schema types
23+
├── tests/ # Cross-package/unit/integration tests
24+
├── README.md
25+
├── package.json
26+
└── nx.json / lerna.json (if using monorepo tool)
27+
```
28+
- Prefer TypeScript for new code; convert JS to TS where feasible.
29+
30+
---
31+
32+
## Extraction & Refactoring Instructions
33+
34+
1. **Audit Source Code**
35+
- Locate all code in `@mixcore/mix.spa.portal` related to "shared", "base", and "apis".
36+
- Include all `.js`, `.ts`, type declaration files, and related JSON/configs if directly used by these modules.
37+
- Exclude SPA-specific or UI-coupled logic.
38+
39+
2. **Migration**
40+
- Move the identified code into the corresponding packages/folders in `mixcore/javascript-sdk`.
41+
- Maintain original directory structure as much as possible for clarity.
42+
- Refactor imports/exports to use package-relative paths.
43+
44+
3. **Decoupling & Configuration**
45+
- Remove or abstract any SPA-coupled dependencies (e.g., window, document, SPA-specific stores).
46+
- Externalize configuration (endpoints, tokens, etc.) using environment variables or injectable configs.
47+
- Ensure all modules are framework-agnostic (no direct Vue/React/Angular dependencies).
48+
49+
4. **Build Outputs**
50+
- Configure builds for both ESM and CJS outputs for maximal compatibility.
51+
- Generate TypeScript type declarations (`.d.ts`).
52+
53+
5. **Testing**
54+
- Write or migrate unit/integration tests for all public APIs.
55+
- Use a test runner compatible with monorepo (e.g., Jest, Vitest).
56+
57+
6. **Documentation**
58+
- Document each package/module with clear usage examples.
59+
- Add migration guides for teams adopting the SDK.
60+
61+
7. **Versioning & Publishing**
62+
- Use semantic versioning (SemVer) for each package or the overall SDK.
63+
- Configure CI/CD pipelines for linting, testing, building, and publishing (npm, GitHub Packages, etc.).
64+
65+
8. **Backward Compatibility**
66+
- Provide clear migration notes for dependent projects.
67+
- Optionally, maintain compatibility layers or adapters if needed.
68+
69+
---
70+
71+
## Usage Scenarios Supported
72+
73+
- **Web Applications:** Import shared logic/API clients directly.
74+
- **Node.js Backends:** Use SDK for server-side scripting, CLI, automation.
75+
- **Microfrontends:** Share core logic across isolated frontend apps.
76+
- **Third-party Plugins/Extensions:** Allow external devs to build on Mixcore APIs safely.
77+
- **Test Automation:** Leverage SDK’s API clients and types.
78+
79+
---
80+
81+
## Security & Compliance
82+
83+
- No secrets or credentials are hardcoded. All sensitive config must be injected at runtime.
84+
- API clients must sanitize all inputs/outputs and handle errors gracefully.
85+
- License the SDK under Mixcore Community License (MCL) or compatible OSS license with clear attribution.
86+
87+
---
88+
89+
## Example SDK Package Metadata (`package.json`)
90+
91+
```json
92+
{
93+
"name": "@mixcore/shared",
94+
"version": "1.0.0",
95+
"main": "dist/index.js",
96+
"module": "dist/index.esm.js",
97+
"types": "dist/index.d.ts",
98+
"license": "SEE LICENSE IN LICENSE",
99+
"repository": "https://github.com/mixcore/javascript-sdk"
100+
}
101+
```
102+
103+
---
104+
105+
## Deliverables
106+
107+
- Extracted and refactored source code in `mixcore/javascript-sdk`
108+
- Complete documentation and migration guides
109+
- CI/CD configuration for automated testing and publishing
110+
- (Optional) Compatibility adapters for legacy consumers
111+
112+
---
113+
114+
## Reference
115+
116+
- Source: [@mixcore/mix.spa.portal](https://github.com/mixcore/mix.spa.portal)
117+
- Target: [mixcore/javascript-sdk](https://github.com/mixcore/javascript-sdk)
118+
- Platform: [Mixcore CMS Overview](https://github.com/mixcore/mix.core)
119+
120+
---
121+
122+
## Approval
123+
124+
This spec serves as the single source of truth for engineering, QA, and product teams for the extraction and modularization process. All future changes and implementation tasks must align with the requirements above.
125+
126+
# Detailed Context for Extraction of Shared, Base, and API Code
127+
128+
## 1. Extraction Scope and Philosophy
129+
130+
- **Goal:** Create a future-proof, reusable, and framework-agnostic JavaScript/TypeScript SDK that contains all utilities, base models, and API integrations previously coupled to the SPA Portal.
131+
- **Principle:** All code in the SDK must be usable outside the context of any specific frontend framework or application.
132+
133+
---
134+
135+
## 2. What to Extract
136+
137+
- All code (in JavaScript or TypeScript) that is:
138+
- **Shared:** Utility functions, constants, validators, formatters, date/time helpers, i18n, etc.
139+
- **Base:** Abstract classes, data models, DTOs, interfaces, inheritance hierarchies.
140+
- **APIs:** API client classes/functions, HTTP request wrappers, endpoint schema types, authentication handlers, API error types, and response mappers.
141+
- **Include:** All related type definitions, interfaces, enums, and any utility that is referenced by shared/base/api modules.
142+
- **Configuration:** Move any constants or config variables (e.g., API endpoints, keys) to injectable/configurable APIs. Do not hardcode environment details.
143+
- **Tests:** Migrate relevant unit and integration tests. If tests are tightly coupled to SPA, adapt them for SDK context.
144+
145+
---
146+
147+
## 3. What to Exclude
148+
149+
- **UI Components:** Vue/React components, CSS/SCSS, HTML templates, or anything tied to rendering.
150+
- **SPA-specific Logic:** Routing, state management (Vuex, Redux, etc.), DOM manipulation, or browser-only APIs unless polyfilled or abstracted.
151+
- **Build/Deploy Scripts:** Unless they are essential for SDK packaging.
152+
153+
---
154+
155+
## 4. SDK Target Architecture
156+
157+
- **Monorepo Structure:** Use Nx, Lerna, or Yarn Workspaces.
158+
- **Packages:**
159+
- `@mixcore/shared`: All generic utilities and stateless helpers.
160+
- `@mixcore/base`: Core abstract models, base classes, reusable interfaces.
161+
- `@mixcore/apis`: API client implementations, endpoints, HTTP logic, auth, error handling.
162+
- **TypeScript Native:** All new code in TypeScript. Convert existing JavaScript to TypeScript where possible.
163+
- **ESM & CJS Outputs:** Build for both module formats.
164+
- **Typed Exports:** All public APIs must export types/interfaces.
165+
- **Framework Agnostic:** No direct dependency on any frontend framework. If needed, provide adapters in optional peer dependencies.
166+
167+
---
168+
169+
## 5. Refactoring Requirements
170+
171+
- **Decouple from SPA:** Remove any direct SPA dependencies. If logic is reused, create adapters or hooks that remain in the SPA repo.
172+
- **Injectable Configuration:** All endpoints, tokens, and environment-specific values must be configured at runtime or via SDK constructors.
173+
- **Error Handling:** Normalize all API error handling. Provide rich, typed errors.
174+
- **Documentation:** All public APIs, types, and configuration points must have TSDoc/JSDoc comments. Each package must have a README.md with usage examples.
175+
176+
---
177+
178+
## 6. Testing & Automation
179+
180+
- **Unit Tests:** For every exported function/class.
181+
- **Integration Tests:** For API clients, using mock servers where possible.
182+
- **CI/CD:** Lint, type-check, test, and build each package on every commit.
183+
- **Versioning:** Per-package semantic versioning (if using monorepo) or global versioning.
184+
185+
---
186+
187+
## 7. Usage Scenarios
188+
189+
- **Web App:** Import SDK modules for shared logic and API access.
190+
- **Node.js Backend:** Use API clients/types for backend scripting.
191+
- **Microfrontends:** Share SDK across independently deployed frontends.
192+
- **Extensions/Plugins:** Third-party developers can build on top of SDK.
193+
- **Testing:** Use SDK for E2E and integration tests in other projects.
194+
195+
---
196+
197+
## 8. Migration Plan
198+
199+
1. **Inventory:** Audit and list all code to move. Map dependencies (internal/external).
200+
2. **Copy & Adapt:** Move code into new SDK repo, preserving structure. Refactor as required.
201+
3. **Refactor Imports:** Update all internal imports to use relative paths or packages.
202+
4. **Test & Validate:** Ensure all moved code passes tests and works independently.
203+
5. **Document:** Write clear docs for each module/package.
204+
6. **Deprecate in SPA:** Update SPA to use SDK, deprecate old code.
205+
206+
---
207+
208+
## 9. Deliverables
209+
210+
- New SDK repository (`mixcore/javascript-sdk`) with:
211+
- Modular packages: `shared`, `base`, `apis`
212+
- Type-safe, framework-agnostic, well-documented code
213+
- Passing tests and CI
214+
- Migration/usage documentation
215+
216+
---
217+
218+
## 10. Success Criteria
219+
220+
- All common logic/API code is reusable across Mixcore projects.
221+
- No SPA or UI dependencies in SDK.
222+
- All public APIs are typed, documented, and tested.
223+
- SDK is easy to consume by first- and third-party developers.

‎.github/workflows/ci.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
package: [apis, base, shared]
15+
steps:
16+
- uses: actions/checkout@v3
17+
- uses: pnpm/action-setup@v2
18+
with:
19+
version: 8
20+
- name: Use Node.js 18
21+
uses: actions/setup-node@v3
22+
with:
23+
node-version: 18
24+
cache: 'pnpm'
25+
- name: Install dependencies
26+
run: pnpm install
27+
- name: Build ${{ matrix.package }}
28+
run: pnpm --filter @mixcore/${{ matrix.package }} build
29+
- name: Run tests for ${{ matrix.package }}
30+
run: pnpm --filter @mixcore/${{ matrix.package }} test

‎.gitignore‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Node modules
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# Logs
8+
npm-debug.log*
9+
yarn-debug.log*
10+
yarn-error.log*
11+
lerna-debug.log*
12+
13+
# IDE
14+
.vscode/
15+
.idea/
16+
.DS_Store
17+
18+
# Test coverage
19+
coverage/
20+
21+
# Misc
22+
.env
23+
.env.*

‎.legacy‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Subproject commit 9935c01a679549c8e362b183dd3c5c5dfb15f94b

‎LICENSE‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
MIT OR Mixcore Community License (MCL)
2+
See https://github.com/mixcore/javascript-sdk for details.

‎README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Mixcore JavaScript SDK
2+
3+
This monorepo contains modular, framework-agnostic packages for Mixcore projects.
4+
5+
## Packages
6+
7+
- **@mixcore/shared**: Utilities, helpers, constants
8+
- **@mixcore/base**: Base classes, abstract models, interfaces
9+
- **@mixcore/apis**: API clients, endpoint wrappers, schema types
10+
11+
## Getting Started
12+
13+
Each package contains its own README with usage examples. See `/packages/*/README.md` for details.
14+
15+
## Development
16+
17+
- All code is TypeScript-first.
18+
- Build outputs: ESM, CJS, and type declarations.
19+
- Tests: Run `npm test` or `yarn test` from the root.
20+
21+
## License
22+
23+
Mixcore Community License (MCL) or compatible OSS license. See LICENSE file for details.

‎lerna.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"packages": [
3+
"packages/*"
4+
],
5+
"version": "independent"
6+
}

‎package.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"name": "@mixcore/javascript-sdk",
3+
"private": true,
4+
"version": "1.0.0",
5+
"description": "Modular, framework-agnostic SDK for Mixcore projects (shared, base, apis)",
6+
"workspaces": [
7+
"packages/*"
8+
],
9+
"scripts": {
10+
"build": "lerna run build --stream",
11+
"test": "lerna run test --stream",
12+
"lint": "lerna run lint --stream"
13+
},
14+
"devDependencies": {
15+
"@types/jest": "^30.0.0",
16+
"@typescript-eslint/eslint-plugin": "^8.38.0",
17+
"@typescript-eslint/parser": "^8.38.0",
18+
"jest": "^30.0.5",
19+
"lerna": "^7.0.0",
20+
"ts-jest": "^29.4.0",
21+
"tsup": "^8.5.0",
22+
"typescript": "^5.8.3"
23+
},
24+
"license": "SEE LICENSE IN LICENSE",
25+
"repository": "https://github.com/mixcore/javascript-sdk",
26+
"packageManager": "[email protected]"
27+
}

‎packages/apis/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# @mixcore/apis
2+
3+
Framework-agnostic API clients for Mixcore modules.
4+
5+
## Usage
6+
7+
```ts
8+
import { ApiService, ModuleArticleService, ModuleDataService, ModuleGalleryService } from '@mixcore/apis';
9+
10+
const api = new ApiService({ apiBaseUrl: 'https://api.example.com' });
11+
const articles = new ModuleArticleService({ apiBaseUrl: 'https://api.example.com' });
12+
```
13+
14+
## Features
15+
- TypeScript-native
16+
- Injectable configuration
17+
- No SPA dependencies
18+
19+
## License
20+
Mixcore Community License (MCL)

0 commit comments

Comments
 (0)