@akinon/projectzero 1.93.0 → 1.94.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: '**'
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Project Zero Next.js App - Developer Instructions
|
|
6
|
+
|
|
7
|
+
## Project Overview
|
|
8
|
+
|
|
9
|
+
This is a **standalone Project Zero Next.js application** - a headless e-commerce storefront built on top of Akinon Commerce Cloud. This app can be cloned and run independently using the `packages/projectzero` command line tool.
|
|
10
|
+
|
|
11
|
+
## Key Characteristics
|
|
12
|
+
|
|
13
|
+
- **Standalone Application**: Can be cloned with `packages/projectzero` CLI and run independently
|
|
14
|
+
- **Next.js 14.2.25**: Uses App Router with dynamic routes
|
|
15
|
+
- **TypeScript**: With relaxed strict mode
|
|
16
|
+
- **E-commerce Focus**: Complete storefront with basket, checkout, payments, user management
|
|
17
|
+
|
|
18
|
+
## Project Structure
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
apps/projectzeronext/
|
|
22
|
+
├── src/
|
|
23
|
+
│ ├── app/[commerce]/[locale]/[currency]/ # App Router pages
|
|
24
|
+
│ ├── components/ # App-specific UI components
|
|
25
|
+
│ ├── views/ # Page-specific view components
|
|
26
|
+
│ ├── hooks/ # Custom React hooks
|
|
27
|
+
│ ├── redux/ # App-specific Redux slices
|
|
28
|
+
│ ├── types/ # App-specific TypeScript types
|
|
29
|
+
│ ├── utils/ # Utility functions
|
|
30
|
+
│ ├── settings.js # Application configuration
|
|
31
|
+
│ ├── routes/ # Route definitions
|
|
32
|
+
│ └── middleware.ts # Next.js middleware
|
|
33
|
+
├── public/ # Static assets
|
|
34
|
+
├── config/ # Configuration files
|
|
35
|
+
├── docs/ # Documentation
|
|
36
|
+
├── package.json # Dependencies and scripts
|
|
37
|
+
├── next.config.mjs # Next.js configuration
|
|
38
|
+
├── tailwind.config.js # TailwindCSS configuration
|
|
39
|
+
└── tsconfig.json # TypeScript configuration
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Core Dependencies
|
|
43
|
+
|
|
44
|
+
### Essential Packages
|
|
45
|
+
|
|
46
|
+
- `@akinon/next`: Core e-commerce functionality (version ^1.93.0)
|
|
47
|
+
- `next`: Next.js framework (14.2.25)
|
|
48
|
+
- `react` & `react-dom`: React framework
|
|
49
|
+
- `@reduxjs/toolkit`: State management
|
|
50
|
+
- `next-auth`: Authentication
|
|
51
|
+
- `react-hook-form`: Form handling
|
|
52
|
+
- `yup`: Form validation
|
|
53
|
+
|
|
54
|
+
### UI & Styling
|
|
55
|
+
|
|
56
|
+
- `tailwindcss`: Utility-first CSS framework
|
|
57
|
+
- `clsx` & `tailwind-merge`: Conditional styling
|
|
58
|
+
- `lucide-react`: Icon library
|
|
59
|
+
|
|
60
|
+
### Plugin Packages
|
|
61
|
+
|
|
62
|
+
The app includes various `pz-*` plugin packages for extended functionality:
|
|
63
|
+
|
|
64
|
+
- `pz-akifast`, `pz-b2b`, `pz-basket-gift-pack`
|
|
65
|
+
- `pz-bkm`, `pz-checkout-gift-pack`, `pz-click-collect`
|
|
66
|
+
- Payment providers: `pz-apple-pay`, `pz-gpay`, `pz-masterpass`, etc.
|
|
67
|
+
|
|
68
|
+
## Architecture Patterns
|
|
69
|
+
|
|
70
|
+
### Route Structure
|
|
71
|
+
|
|
72
|
+
- Dynamic routes: `/[commerce]/[locale]/[currency]/`
|
|
73
|
+
- App Router with server and client components
|
|
74
|
+
- Middleware for routing and internationalization
|
|
75
|
+
|
|
76
|
+
### Data Fetching
|
|
77
|
+
|
|
78
|
+
- **RTK Query** for API calls
|
|
79
|
+
- Server components for initial data
|
|
80
|
+
- Client components with hooks for interactivity
|
|
81
|
+
- Example patterns:
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
// Server component data fetching
|
|
85
|
+
const basketData = await getBasket();
|
|
86
|
+
|
|
87
|
+
// Client component hooks
|
|
88
|
+
const { data: basket } = useGetBasketQuery();
|
|
89
|
+
const [addToBasket] = useAddProductToBasketMutation();
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### State Management
|
|
93
|
+
|
|
94
|
+
- **Redux Toolkit** with key slices:
|
|
95
|
+
- `checkout`: Multi-step checkout flow
|
|
96
|
+
- `basket`: Shopping cart state
|
|
97
|
+
- `header`: Navigation state
|
|
98
|
+
- `root`: Global app state
|
|
99
|
+
- Use `useAppSelector` and `useAppDispatch`
|
|
100
|
+
|
|
101
|
+
### Component Architecture
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
// Theme components (app-specific)
|
|
105
|
+
import { Button, Input } from '@theme/components';
|
|
106
|
+
|
|
107
|
+
// Core components (from @akinon/next)
|
|
108
|
+
import { Image } from '@akinon/next/components/image';
|
|
109
|
+
|
|
110
|
+
// Plugin system
|
|
111
|
+
import PluginModule, { Component } from '@akinon/next/components/plugin-module';
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Forms & Validation
|
|
115
|
+
|
|
116
|
+
Standard pattern with React Hook Form + Yup:
|
|
117
|
+
|
|
118
|
+
```tsx
|
|
119
|
+
const schema = (t) =>
|
|
120
|
+
yup.object().shape({
|
|
121
|
+
email: yup.string().email().required(t('error.required')),
|
|
122
|
+
password: yup.string().min(6).required(t('error.required'))
|
|
123
|
+
});
|
|
124
|
+
|
|
125
|
+
const {
|
|
126
|
+
register,
|
|
127
|
+
handleSubmit,
|
|
128
|
+
formState: { errors }
|
|
129
|
+
} = useForm({
|
|
130
|
+
resolver: yupResolver(schema(t))
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## E-commerce Features
|
|
135
|
+
|
|
136
|
+
### Core Functionality
|
|
137
|
+
|
|
138
|
+
- **Product Catalog**: Browse, search, filter products
|
|
139
|
+
- **Basket Management**: Add/remove items, quantity updates
|
|
140
|
+
- **Checkout Flow**: Multi-step process (auth → shipping → payment → confirmation)
|
|
141
|
+
- **User Accounts**: Registration, login, order history
|
|
142
|
+
- **Payment Integration**: Multiple payment providers
|
|
143
|
+
- **Order Management**: Track orders, view history
|
|
144
|
+
|
|
145
|
+
### Internationalization
|
|
146
|
+
|
|
147
|
+
- Multi-language support with `useLocalization()` hook
|
|
148
|
+
- Dynamic locale routing: `/[locale]/`
|
|
149
|
+
- Translation keys: `t('checkout.auth.title')`
|
|
150
|
+
- Settings configuration in `src/settings.js`
|
|
151
|
+
|
|
152
|
+
### Authentication
|
|
153
|
+
|
|
154
|
+
- NextAuth.js integration
|
|
155
|
+
- Session management with `useSession()`
|
|
156
|
+
- Protected routes via middleware
|
|
157
|
+
- User account features
|
|
158
|
+
|
|
159
|
+
## Development Guidelines
|
|
160
|
+
|
|
161
|
+
### File Naming & Structure
|
|
162
|
+
|
|
163
|
+
- Components: PascalCase (`ProductCard.tsx`)
|
|
164
|
+
- Pages: kebab-case in App Router directories
|
|
165
|
+
- Hooks: camelCase starting with `use` (`useBasket.ts`)
|
|
166
|
+
- Types: PascalCase with descriptive names (`ProductType.ts`)
|
|
167
|
+
|
|
168
|
+
### Import Conventions
|
|
169
|
+
|
|
170
|
+
```tsx
|
|
171
|
+
// Path aliases (configured in tsconfig.json)
|
|
172
|
+
import { Button } from '@theme/components'; // App components
|
|
173
|
+
import { Image } from '@akinon/next/components'; // Core components
|
|
174
|
+
import { useLocalization } from '@akinon/next/hooks'; // Core hooks
|
|
175
|
+
import { ProductType } from '@akinon/next/types'; // Core types
|
|
176
|
+
import { routes } from '@root/routes'; // App routes
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Styling Guidelines
|
|
180
|
+
|
|
181
|
+
- **TailwindCSS** for all styling
|
|
182
|
+
- Use `clsx` and `twMerge` for conditional classes
|
|
183
|
+
- Responsive design: mobile-first approach
|
|
184
|
+
- Theme customization in `tailwind.config.js`
|
|
185
|
+
|
|
186
|
+
### Performance Best Practices
|
|
187
|
+
|
|
188
|
+
- Lazy loading with `LazyComponent`
|
|
189
|
+
- Next.js `Image` component for optimized images
|
|
190
|
+
- Code splitting with dynamic imports
|
|
191
|
+
- Intersection Observer for viewport-based loading
|
|
192
|
+
|
|
193
|
+
## Development Commands
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
# Development
|
|
197
|
+
yarn dev # Start development server
|
|
198
|
+
yarn build # Build for production
|
|
199
|
+
yarn start # Start production server
|
|
200
|
+
|
|
201
|
+
# Code Quality
|
|
202
|
+
yarn lint # Run ESLint
|
|
203
|
+
yarn lint:fix # Fix ESLint issues
|
|
204
|
+
yarn type-check # TypeScript type checking
|
|
205
|
+
|
|
206
|
+
# Testing
|
|
207
|
+
yarn test # Run Jest tests
|
|
208
|
+
yarn test:watch # Run tests in watch mode
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Configuration Files
|
|
212
|
+
|
|
213
|
+
### Key Config Files
|
|
214
|
+
|
|
215
|
+
- `next.config.mjs`: Next.js configuration
|
|
216
|
+
- `tailwind.config.js`: TailwindCSS theme and plugins
|
|
217
|
+
- `src/settings.js`: App-specific settings (commerce, locales, etc.)
|
|
218
|
+
- `src/middleware.ts`: Route handling and internationalization
|
|
219
|
+
- `package.json`: Dependencies and scripts
|
|
220
|
+
|
|
221
|
+
### Environment Variables
|
|
222
|
+
|
|
223
|
+
Configure in `.env.local`:
|
|
224
|
+
|
|
225
|
+
- `NEXTAUTH_SECRET`: Authentication secret
|
|
226
|
+
- `NEXTAUTH_URL`: Application URL
|
|
227
|
+
- Commerce API endpoints
|
|
228
|
+
- Payment provider configurations
|
|
229
|
+
|
|
230
|
+
## Plugin System
|
|
231
|
+
|
|
232
|
+
### Using Plugins
|
|
233
|
+
|
|
234
|
+
```tsx
|
|
235
|
+
import PluginModule, { Component } from '@akinon/next/components/plugin-module';
|
|
236
|
+
|
|
237
|
+
// Conditional plugin rendering
|
|
238
|
+
<PluginModule component={Component.BasketGiftPack} props={{ basket }} />;
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Available Plugins
|
|
242
|
+
|
|
243
|
+
- **Payment**: Apple Pay, Google Pay, BKM, Masterpass
|
|
244
|
+
- **Checkout**: Gift packs, click & collect, one-click checkout
|
|
245
|
+
- **Business**: B2B features, multi-basket, saved cards
|
|
246
|
+
- **Regional**: Tabby, Tamara (MENA region)
|
|
247
|
+
|
|
248
|
+
## Important Notes
|
|
249
|
+
|
|
250
|
+
### Critical Middleware
|
|
251
|
+
|
|
252
|
+
- **Never remove** `withPzDefault` middleware - essential for app functionality
|
|
253
|
+
- Middleware handles routing, locale detection, commerce resolution
|
|
254
|
+
|
|
255
|
+
### State Management
|
|
256
|
+
|
|
257
|
+
- Checkout uses multi-step Redux flow
|
|
258
|
+
- Basket state syncs with backend APIs
|
|
259
|
+
- User session integrates with NextAuth
|
|
260
|
+
|
|
261
|
+
### SEO & Analytics
|
|
262
|
+
|
|
263
|
+
- GTM integration for e-commerce tracking
|
|
264
|
+
- Server-side rendering for SEO
|
|
265
|
+
- Structured data for products
|
|
266
|
+
|
|
267
|
+
### Deployment
|
|
268
|
+
|
|
269
|
+
- Can be deployed standalone
|
|
270
|
+
- Supports various hosting platforms
|
|
271
|
+
- Environment-specific configurations
|
|
272
|
+
|
|
273
|
+
When working with this app, always consider:
|
|
274
|
+
|
|
275
|
+
1. **E-commerce context**: Every feature impacts the shopping experience
|
|
276
|
+
2. **Plugin architecture**: Use modular approach for features
|
|
277
|
+
3. **Internationalization**: Support multiple languages/regions
|
|
278
|
+
4. **Performance**: Optimize for mobile commerce
|
|
279
|
+
5. **Standalone nature**: App should work independently when cloned
|
|
@@ -1,5 +1,47 @@
|
|
|
1
1
|
# projectzeronext
|
|
2
2
|
|
|
3
|
+
## 1.94.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 6e6b0a9: ZERO-3422: Add pz-flow-payment package
|
|
8
|
+
- adf0eeb: ZERO-3597: Add copilot instruction files
|
|
9
|
+
- c806fad: ZERO-3422: Add Flow Payment plugin to the defined plugins list
|
|
10
|
+
- 72ad7bb: ZERO-3422: Add Flow Payment to the list of available plugins
|
|
11
|
+
|
|
12
|
+
### Patch Changes
|
|
13
|
+
|
|
14
|
+
- Updated dependencies [6e6b0a9]
|
|
15
|
+
- Updated dependencies [adf0eeb]
|
|
16
|
+
- Updated dependencies [c806fad]
|
|
17
|
+
- Updated dependencies [1b4c343]
|
|
18
|
+
- Updated dependencies [0abde6b]
|
|
19
|
+
- Updated dependencies [72ad7bb]
|
|
20
|
+
- Updated dependencies [e7cd3a5]
|
|
21
|
+
- Updated dependencies [17bfadc]
|
|
22
|
+
- Updated dependencies [dfaceff]
|
|
23
|
+
- Updated dependencies [86642cf]
|
|
24
|
+
- Updated dependencies [485e8ef]
|
|
25
|
+
- Updated dependencies [fec9638]
|
|
26
|
+
- Updated dependencies [b434ac8]
|
|
27
|
+
- Updated dependencies [fee608d]
|
|
28
|
+
- @akinon/next@1.94.0
|
|
29
|
+
- @akinon/pz-click-collect@1.94.0
|
|
30
|
+
- @akinon/pz-credit-payment@1.94.0
|
|
31
|
+
- @akinon/pz-akifast@1.94.0
|
|
32
|
+
- @akinon/pz-b2b@1.94.0
|
|
33
|
+
- @akinon/pz-basket-gift-pack@1.94.0
|
|
34
|
+
- @akinon/pz-bkm@1.94.0
|
|
35
|
+
- @akinon/pz-checkout-gift-pack@1.94.0
|
|
36
|
+
- @akinon/pz-gpay@1.94.0
|
|
37
|
+
- @akinon/pz-masterpass@1.94.0
|
|
38
|
+
- @akinon/pz-one-click-checkout@1.94.0
|
|
39
|
+
- @akinon/pz-otp@1.94.0
|
|
40
|
+
- @akinon/pz-pay-on-delivery@1.94.0
|
|
41
|
+
- @akinon/pz-saved-card@1.94.0
|
|
42
|
+
- @akinon/pz-tabby-extension@1.94.0
|
|
43
|
+
- @akinon/pz-tamara-extension@1.94.0
|
|
44
|
+
|
|
3
45
|
## 1.93.0
|
|
4
46
|
|
|
5
47
|
### Patch Changes
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "projectzeronext",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.94.0",
|
|
4
4
|
"private": true,
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"scripts": {
|
|
@@ -24,22 +24,22 @@
|
|
|
24
24
|
"test:middleware": "jest middleware-matcher.test.ts --bail"
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"@akinon/next": "1.
|
|
28
|
-
"@akinon/pz-akifast": "1.
|
|
29
|
-
"@akinon/pz-b2b": "1.
|
|
30
|
-
"@akinon/pz-basket-gift-pack": "1.
|
|
31
|
-
"@akinon/pz-bkm": "1.
|
|
32
|
-
"@akinon/pz-checkout-gift-pack": "1.
|
|
33
|
-
"@akinon/pz-click-collect": "1.
|
|
34
|
-
"@akinon/pz-credit-payment": "1.
|
|
35
|
-
"@akinon/pz-gpay": "1.
|
|
36
|
-
"@akinon/pz-masterpass": "1.
|
|
37
|
-
"@akinon/pz-one-click-checkout": "1.
|
|
38
|
-
"@akinon/pz-otp": "1.
|
|
39
|
-
"@akinon/pz-pay-on-delivery": "1.
|
|
40
|
-
"@akinon/pz-saved-card": "1.
|
|
41
|
-
"@akinon/pz-tabby-extension": "1.
|
|
42
|
-
"@akinon/pz-tamara-extension": "1.
|
|
27
|
+
"@akinon/next": "1.94.0",
|
|
28
|
+
"@akinon/pz-akifast": "1.94.0",
|
|
29
|
+
"@akinon/pz-b2b": "1.94.0",
|
|
30
|
+
"@akinon/pz-basket-gift-pack": "1.94.0",
|
|
31
|
+
"@akinon/pz-bkm": "1.94.0",
|
|
32
|
+
"@akinon/pz-checkout-gift-pack": "1.94.0",
|
|
33
|
+
"@akinon/pz-click-collect": "1.94.0",
|
|
34
|
+
"@akinon/pz-credit-payment": "1.94.0",
|
|
35
|
+
"@akinon/pz-gpay": "1.94.0",
|
|
36
|
+
"@akinon/pz-masterpass": "1.94.0",
|
|
37
|
+
"@akinon/pz-one-click-checkout": "1.94.0",
|
|
38
|
+
"@akinon/pz-otp": "1.94.0",
|
|
39
|
+
"@akinon/pz-pay-on-delivery": "1.94.0",
|
|
40
|
+
"@akinon/pz-saved-card": "1.94.0",
|
|
41
|
+
"@akinon/pz-tabby-extension": "1.94.0",
|
|
42
|
+
"@akinon/pz-tamara-extension": "1.94.0",
|
|
43
43
|
"@hookform/resolvers": "2.9.0",
|
|
44
44
|
"@next/third-parties": "14.1.0",
|
|
45
45
|
"@react-google-maps/api": "2.17.1",
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
"yup": "0.32.11"
|
|
63
63
|
},
|
|
64
64
|
"devDependencies": {
|
|
65
|
-
"@akinon/eslint-plugin-projectzero": "1.
|
|
65
|
+
"@akinon/eslint-plugin-projectzero": "1.94.0",
|
|
66
66
|
"@semantic-release/changelog": "6.0.2",
|
|
67
67
|
"@semantic-release/exec": "6.0.3",
|
|
68
68
|
"@semantic-release/git": "10.0.1",
|
package/commands/plugins.ts
CHANGED
package/dist/commands/plugins.js
CHANGED