@longtq2501/next-spring-skills 1.2.0 → 1.4.0

package/AGENT.md

@@ -1,5 +1,8 @@
 # Agent Instructions
 
+> [!IMPORTANT]
+> **MANDATORY STARTUP STEP**: Upon starting a new session or entering this project, the AI Agent **MUST** immediately read `skills/SKILL.md` to index all available standards and architectural patterns. Do not proceed with code generation until you have understood the patterns in the `skills/` directory.
+
 Rules for contributing to this repository.
 
 ## Style Guidelines

package/README.md

@@ -1,5 +1,7 @@
 # Next-Spring Skills
 
+[![npm version](https://img.shields.io/npm/v/@longtq2501/next-spring-skills.svg)](https://www.npmjs.com/package/@longtq2501/next-spring-skills)
+
 Modular best practices, code templates, and interaction protocols for full-stack projects using **Next.js** and **Spring Boot**.
 
 ## Key Directories
@@ -11,6 +13,11 @@ Modular best practices, code templates, and interaction protocols for full-stack
 
 ---
 
+## NPM Package
+📦 **Registry**: [https://www.npmjs.com/package/@longtq2501/next-spring-skills](https://www.npmjs.com/package/@longtq2501/next-spring-skills)
+
+---
+
 ## Installation
 You can instantly add these skills to any project using `npx`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtq2501/next-spring-skills",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Standardized best practices and code patterns for Next.js and Spring Boot",
   "bin": {
     "next-spring-skills": "bin/cli.js"

package/skills/SKILL.md

@@ -66,6 +66,12 @@ See [threejs.md](./nextjs/threejs.md) for high-performance 3D development and R3
 ### WebRTC & P2P
 See [webrtc.md](./nextjs/webrtc.md) for real-time media and signaling.
 
+### Quality Assurance
+See [testing.md](./nextjs/testing.md) for Vitest and React Testing Library patterns.
+
+### Architecture & Monorepo
+See [monorepo.md](./nextjs/monorepo.md) for Turborepo and code-sharing strategies.
+
 ### Accessibility (a11y)
 See [accessibility.md](./nextjs/accessibility.md) for semantic HTML and ARIA.
 
@@ -118,6 +124,9 @@ High-performance, stateless REST API patterns using Spring Boot, JPA, and JWT.
 - [WebSocket & STOMP](./spring/websocket.md)
 - [Server-Sent Events (SSE)](./spring/sse.md)
 
+### Quality Assurance
+- [Backend Testing](./spring/testing.md)
+
 ---
 
 **Templates:** See the [spring/templates/](./spring/templates/) directory for production-ready boilerplates.

package/skills/nextjs/monorepo.md

@@ -0,0 +1,116 @@
+# Skill: Monorepo Management - Turborepo (Production Blueprint)
+
+Guidelines for building a scalable, high-performance monorepo for enterprise-level multi-platform projects.
+
+## TL;DR - Quick Reference
+
+### Critical Rules
+1. **Orchestration**: Use Turborepo for build pipeline and remote caching.
+2. **Modular Packages**: Extract logic to `packages/` to ensure 95%+ code reusability.
+3. **Internal Linking**: Use `workspace:*` for local package dependencies.
+4. **Consistency**: Share ESLint, Prettier, Tailwind, and TS configs across all apps.
+5. **Types First**: Shared DTOs in `packages/types` are the single source of truth for FE/BE sync.
+
+---
+
+## 1. Enterprise Directory Structure
+
+```text
+/my-monorepo/
+├── apps/                           # Deployable Applications
+│   ├── web/                        # Next.js 14 App Router
+│   ├── admin/                      # Admin Dashboard
+│   ├── mobile/                     # React Native (Expo)
+│   ├── desktop/                    # Electron
+│   └── api/                        # Spring Boot (Backend)
+├── packages/                       # Shared Domain Logic
+│   ├── ui/                         # Core UI (Shadcn/React)
+│   ├── types/                      # Shared Interfaces & DTOs
+│   ├── validators/                 # Zod/Validation Logic
+│   ├── utils/                      # Shared Helpers (Date, String)
+│   ├── api-client/                 # Axios/Fetch Wrapper
+│   └── database/                   # Prisma/DB Client
+├── infra/                          # Shared Configuration
+│   ├── tailwind-config/
+│   ├── eslint-config/
+│   └── typescript-config/
+├── turbo.json                      # Build Pipeline Config
+└── package.json                    # Workspace Definition
+```
+
+---
+
+## 2. Core Configurations
+
+### turbo.json (The Brain)
+Defines task dependencies and caching outputs.
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": [".next/**", "dist/**", "out/**"]
+    },
+    "lint": {},
+    "test": {
+      "cache": true
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+### package.json (The Workspace)
+Must include `workspaces` (npm/yarn) or `pnpm-workspace.yaml`.
+
+```json
+{
+  "private": true,
+  "workspaces": ["apps/*", "packages/*"],
+  "scripts": {
+    "dev": "turbo dev",
+    "build": "turbo build",
+    "test": "turbo test"
+  }
+}
+```
+
+---
+
+## 3. Shared Packages Pattern
+
+### How to share a package (ex: Types)
+1. Create `packages/types/package.json` with a scoped name like `@repo/types`.
+2. Export your types/interfaces from `index.ts`.
+3. In `apps/web/package.json`, add `"@repo/types": "workspace:*"`.
+
+// Good: Shared DTO Example
+export interface OrderDTO {
+  id: string;
+  status: 'PENDING' | 'DONE';
+  items: string[];
+}
+
+---
+
+## 4. Scaling & Efficiency
+
+### Remote Caching
+Enable `turbo login` and `turbo link` in CI/CD to share build artifacts across the team, reducing build times from minutes to seconds.
+
+### Monolith to Monorepo Migration
+- **Step 1**: Move your monolithic `src/` to `apps/main-app/`.
+- **Step 2**: Identify shared logic (utils, constants) and move them to `packages/`.
+- **Step 3**: Introduce internal packages and replace local imports with `@repo/...`.
+
+---
+
+## Related Skills
+- **Frontend Testing**: `skills/nextjs/testing.md`
+- **Performance**: `skills/nextjs/performance.md`
+- **Agent Workflow**: `skills/agent-workflow.md`

package/skills/nextjs/testing.md

@@ -0,0 +1,86 @@
+# Skill: Frontend Testing - Vitest & RTL
+
+Guidelines for testing React components and logic using Vitest and React Testing Library (RTL).
+
+## TL;DR - Quick Reference
+
+### Critical Rules
+1. **User-Centric Testing**: Test how the user interacts with the app (e.g., clicking buttons), not implementation details (e.g., state).
+2. **Vitest**: Use Vitest for speed and compatibility with Vite/Next.js.
+3. **Screen Queries**: Prefer `getByRole`, `getByLabelText`, and `getByText` over `test-id`.
+4. **Mocking**: Use `vi.mock()` for modules and **MSW (Mock Service Worker)** for API calls.
+5. **Async Handling**: Use `findBy...` or `waitFor` to handle elements that appear after an async operation.
+
+---
+
+## 1. Utility & Logic Testing (Vitest)
+Test pure JavaScript/TypeScript functions and logic.
+
+// Good: Testing a utility function
+import { describe, it, expect } from 'vitest';
+import { calculateTotal } from './math';
+
+describe('calculateTotal', () => {
+  it('should sum items correctly with tax', () => {
+    const items = [{ price: 100 }, { price: 200 }];
+    const result = calculateTotal(items, 0.1);
+    expect(result).toBe(330);
+  });
+});
+
+---
+
+## 2. Component Testing (React Testing Library)
+Test UI behavior and interaction.
+
+// Good: Testing a Button component
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Button } from './Button';
+
+it('should call onClick when clicked', () => {
+  const handleClick = vi.fn();
+  render(<Button onClick={handleClick}>Click Me</Button>);
+  
+  fireEvent.click(screen.getByText(/click me/i));
+  
+  expect(handleClick).toHaveBeenCalledTimes(1);
+});
+
+---
+
+## 3. Async & API Testing (MSW)
+Using Mock Service Worker to intercept network requests.
+
+// Good: Testing a component that fetches data
+it('should display products from API', async () => {
+  render(<ProductList />);
+  
+  // findBy queries are async and will wait
+  const item = await screen.findByText('Laptop');
+  expect(item).toBeInTheDocument();
+});
+
+---
+
+## 4. Hooks Testing
+Use `@testing-library/react-hooks` or the built-in `renderHook` from RTL.
+
+// Good: Testing a custom hook
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './useCounter';
+
+it('should increment counter', () => {
+  const { result } = renderHook(() => useCounter());
+  
+  act(() => {
+    result.current.increment();
+  });
+
+  expect(result.current.count).toBe(1);
+});
+
+---
+
+## Related Skills
+- **Interactivity & Animation**: `skills/nextjs/interactivity.md`
+- **Performance**: `skills/nextjs/performance.md`

package/skills/spring/testing.md

@@ -0,0 +1,104 @@
+# Skill: Backend Testing - Spring Boot
+
+Guidelines for implementing a robust testing pyramid (Unit, Integration, and API tests).
+
+## TL;DR - Quick Reference
+
+### Critical Rules
+1. **Testing Pyramid**: Focus on many Unit tests, fewer Integration tests, and even fewer E2E tests.
+2. **First Law**: Tests must be **Fast**, **Independent**, **Repeatable**, **Self-validating**, and **Timely**.
+3. **Mocking**: Use `@Mock` and `@InjectMocks` for unit tests. Never use `@SpringBootTest` for unit tests.
+4. **Data Isolation**: Always use `@DataJpaTest` for repository testing and avoid modifying production databases.
+5. **Assertions**: Use **AssertJ** (`assertThat`) for readable and powerful assertions.
+
+---
+
+## 1. Unit Testing (JUnit 5 + Mockito)
+Test business logic in isolation. **No Spring context loaded.**
+
+// Good: Testing Service logic with Mocks
+@ExtendWith(MockitoExtension.class)
+class ProductServiceTest {
+    @Mock
+    private ProductRepository repo;
+    
+    @InjectMocks
+    private ProductService service;
+
+    @Test
+    void shouldCalculateTaxCorrect() {
+        // Given
+        Product p = new Product(100.0);
+        when(repo.findById(1L)).thenReturn(Optional.of(p));
+
+        // When
+        double result = service.getTaxedPrice(1L);
+
+        // Then
+        assertThat(result).isEqualTo(110.0);
+        verify(repo).findById(1L);
+    }
+}
+
+---
+
+## 2. Slice/API Testing (@WebMvcTest)
+Testing controllers without booting the whole application. Uses **MockMvc**.
+
+// Good: Testing Controller endpoints
+@WebMvcTest(ProductController.class)
+class ProductControllerTest {
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private ProductService service;
+
+    @Test
+    void shouldReturnProductList() throws Exception {
+        when(service.getAll()).thenReturn(List.of(new ProductDTO("PC")));
+
+        mockMvc.perform(get("/api/products"))
+               .andExpect(status().isOk())
+               .andExpect(jsonPath("$[0].name").value("PC"));
+    }
+}
+
+---
+
+## 3. Integration Testing (@SpringBootTest)
+Testing the full application stack, including database and security.
+
+// Good: Integration test with Testcontainers
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@Testcontainers
+class OrderIntegrationTest {
+    
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
+
+    @Autowired
+    private TestRestTemplate restTemplate;
+
+    @Test
+    void shouldCreateOrderRealInDB() {
+        OrderRequest req = new OrderRequest("User1", 500);
+        ResponseEntity<OrderResponse> res = restTemplate.postForEntity("/api/orders", req, OrderResponse.class);
+
+        assertThat(res.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        assertThat(res.getBody().getId()).isNotNull();
+    }
+}
+
+---
+
+## 4. Best Practices Checklist
+- **Coverage**: Aim for 80%+ line coverage in Services, but focus on the "Happy Path" and "Edge Cases" rather than just the number.
+- **Naming**: Use `should_DoSomething_When_Scenario` or `methodName_stateUnderTest_expectedBehavior`.
+- **No Flaky Tests**: Avoid tests that depend on system time, random numbers, or network latency without mocking.
+
+---
+
+## Related Skills
+- **Service Design**: `skills/spring/service_design.md`
+- **Error Handling**: `skills/spring/error_handling.md`