Skip to content

Commit e7f680d

Browse files
mashrulhaquemashrulhaque
committed
Add new documentation pages for Middleware, Migration, Performance, Persistence, and State Management
- Created middleware.html for custom middleware documentation. - Added migration.html to guide users from v1 to v2. - Introduced performance.html focusing on optimization techniques. - Developed persistence.html for state persistence with LocalStorage. - Established state-management.html detailing advanced state management patterns.
1 parent 0e287df commit e7f680d

63 files changed

Lines changed: 3869 additions & 284 deletions

Some content is hidden

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

‎.github/workflows/deploy-docs.yml‎

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -27,30 +27,13 @@ jobs:
2727
- name: Checkout
2828
uses: actions/checkout@v4
2929

30-
- name: Setup Node.js
31-
uses: actions/setup-node@v4
32-
with:
33-
node-version: '18'
34-
cache: 'npm'
35-
cache-dependency-path: docs-site/package-lock.json
36-
37-
- name: Install dependencies
38-
working-directory: ./docs-site
39-
run: npm ci
40-
41-
- name: Build docs
42-
working-directory: ./docs-site
43-
env:
44-
GITHUB_PAGES: 'true'
45-
run: npm run build
46-
4730
- name: Setup Pages
4831
uses: actions/configure-pages@v4
4932

5033
- name: Upload artifact
5134
uses: actions/upload-pages-artifact@v3
5235
with:
53-
path: './docs-site/dist'
36+
path: './docs-site'
5437

5538
deploy:
5639
environment:

docs-site/.gitignore renamed to docs-site-react-backup/.gitignore

File renamed without changes.

‎docs-site-react-backup/README.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# EasyAppDev.Blazor.Store Documentation Website
2+
3+
Modern, interactive documentation website for EasyAppDev.Blazor.Store built with React and Vite.
4+
5+
**🌐 Live Site:** [https://mashrulhaque.github.io/EasyAppDev.Blazor.Store/](https://mashrulhaque.github.io/EasyAppDev.Blazor.Store/)
6+
7+
## About the Library
8+
9+
**EasyAppDev.Blazor.Store** is a Zustand-inspired state management library for Blazor applications. It emphasizes simplicity, type safety, and immutability with minimal boilerplate.
10+
11+
**Key Library Features:**
12+
- ✨ **Zero boilerplate** - Write state methods, not actions/reducers
13+
- 🔒 **Immutable by default** - C# records + `with` expressions
14+
- 🎯 **Automatic reactivity** - Components update automatically
15+
- ⚡ **5 async helpers** - UpdateDebounced, AsyncData<T>, ExecuteAsync, UpdateThrottled, LazyLoad (74% code reduction)
16+
- 📦 **Tiny** - Only 38 KB gzipped
17+
- 🧰 **Redux DevTools** - Time-travel debugging
18+
19+
## Documentation Site Features
20+
21+
- 📚 **Multi-Page Documentation** - Comprehensive coverage of all library features
22+
- 🎨 **Syntax Highlighting** - Beautiful code examples with Prism.js
23+
- 📱 **Responsive Design** - Works perfectly on desktop, tablet, and mobile
24+
- ⚡ **Fast Performance** - Built with Vite for lightning-fast development
25+
- 🧭 **Easy Navigation** - Sidebar navigation with clear hierarchy
26+
- 🎯 **Focused Content** - Each page dedicated to a specific topic
27+
- ⚙️ **Async Helpers Showcase** - Detailed documentation for v2.0 features
28+
29+
## Getting Started
30+
31+
### Prerequisites
32+
33+
- Node.js 18.0 or higher
34+
- npm or yarn
35+
36+
### Installation
37+
38+
```bash
39+
cd docs-site
40+
npm install
41+
```
42+
43+
### Development
44+
45+
Run the development server:
46+
47+
```bash
48+
npm run dev
49+
```
50+
51+
The site will be available at `http://localhost:3000`
52+
53+
### Build for Production
54+
55+
```bash
56+
npm run build
57+
```
58+
59+
The built site will be in the `dist/` directory.
60+
61+
For GitHub Pages deployment, the build uses the `GITHUB_PAGES=true` environment variable to set the correct base path:
62+
63+
```bash
64+
GITHUB_PAGES=true npm run build
65+
```
66+
67+
### Preview Production Build
68+
69+
```bash
70+
npm run preview
71+
```
72+
73+
## Deployment
74+
75+
The documentation site is automatically deployed to GitHub Pages via GitHub Actions.
76+
77+
### Automatic Deployment
78+
79+
The site deploys automatically when:
80+
- Changes are pushed to the `main` branch
81+
- Files in `docs-site/**` are modified
82+
- The workflow file `.github/workflows/deploy-docs.yml` is changed
83+
84+
### Manual Deployment
85+
86+
You can manually trigger a deployment:
87+
1. Go to the [Actions tab](https://github.com/mashrulhaque/EasyAppDev.Blazor.Store/actions)
88+
2. Select "Deploy Docs to GitHub Pages"
89+
3. Click "Run workflow" → Select "main" branch → "Run workflow"
90+
91+
### Deployment Configuration
92+
93+
The deployment is configured via:
94+
- **Workflow:** `.github/workflows/deploy-docs.yml`
95+
- **Base Path:** Set in `vite.config.js` via `process.env.GITHUB_PAGES`
96+
- **Router:** React Router uses `basename={import.meta.env.BASE_URL}`
97+
- **Output:** `dist/` directory is deployed to GitHub Pages
98+
99+
## Project Structure
100+
101+
```
102+
docs-site/
103+
├── src/
104+
│ ├── components/
105+
│ │ ├── Layout/ # Main layout with sidebar
106+
│ │ │ ├── Layout.jsx
107+
│ │ │ └── Layout.css
108+
│ │ ├── CodeBlock/ # Syntax-highlighted code blocks
109+
│ │ │ ├── CodeBlock.jsx
110+
│ │ │ └── CodeBlock.css
111+
│ │ └── Alert/ # Alert/notice components
112+
│ │ ├── Alert.jsx
113+
│ │ └── Alert.css
114+
│ ├── pages/
115+
│ │ ├── Home.jsx # Landing page
116+
│ │ ├── GettingStarted.jsx
117+
│ │ ├── CoreConcepts.jsx
118+
│ │ ├── AsyncHelpers/ # v2.0 Async Helpers
119+
│ │ │ ├── AsyncHelpers.jsx # Overview
120+
│ │ │ ├── UpdateDebounced.jsx
121+
│ │ │ ├── AsyncData.jsx
122+
│ │ │ ├── ExecuteAsync.jsx
123+
│ │ │ ├── UpdateThrottled.jsx
124+
│ │ │ └── LazyLoad.jsx
125+
│ │ ├── Performance.jsx
126+
│ │ ├── StateManagement.jsx
127+
│ │ ├── Components.jsx
128+
│ │ ├── DevTools.jsx
129+
│ │ ├── Persistence.jsx
130+
│ │ ├── Middleware.jsx
131+
│ │ ├── BestPractices.jsx
132+
│ │ ├── Migration.jsx
133+
│ │ ├── Examples.jsx
134+
│ │ └── APIReference.jsx
135+
│ ├── App.jsx # React Router setup
136+
│ ├── main.jsx # Entry point
137+
│ └── index.css # Global styles
138+
├── index.html
139+
├── vite.config.js
140+
└── package.json
141+
```
142+
143+
## Navigation Structure
144+
145+
The documentation is organized into logical sections:
146+
147+
### Getting Started
148+
- Introduction
149+
- Quick Start
150+
- Core Concepts
151+
152+
### Core Features
153+
- State Management
154+
- Components
155+
- Performance
156+
157+
### Async Helpers (v2.0)
158+
- Overview
159+
- UpdateDebounced
160+
- AsyncData<T>
161+
- ExecuteAsync
162+
- UpdateThrottled
163+
- LazyLoad
164+
165+
### Advanced
166+
- DevTools
167+
- Persistence
168+
- Middleware
169+
170+
### Resources
171+
- Best Practices
172+
- Migration Guide
173+
- Examples
174+
- API Reference
175+
176+
## Key Pages
177+
178+
### Home (`/`)
179+
- Overview of the library
180+
- Key features and benefits
181+
- Quick start guide
182+
- What's new in v2.0
183+
184+
### Getting Started (`/getting-started`)
185+
- Installation instructions
186+
- 3-step setup guide
187+
- First component example
188+
- Next steps
189+
190+
### Async Helpers (`/async-helpers`)
191+
- Overview of all async helpers
192+
- Code reduction statistics
193+
- Before/after comparisons
194+
- Links to individual helper pages
195+
196+
### Individual Async Helper Pages
197+
Each async helper has a dedicated page with:
198+
- Problem statement
199+
- Solution overview
200+
- Complete code examples
201+
- API reference
202+
- Best practices
203+
- Use cases
204+
- Performance metrics
205+
206+
## Technologies Used
207+
208+
- **React 18.2** - UI library
209+
- **React Router 6.20** - Client-side routing
210+
- **Vite 5.0** - Build tool and dev server
211+
- **Prism.js 1.29** - Syntax highlighting
212+
- **React Icons 4.12** - Icon library
213+
214+
## Design Principles
215+
216+
1. **Developer-Focused** - Clear, concise explanations with plenty of code examples
217+
2. **Progressive Disclosure** - Quick start first, deep dives available
218+
3. **Copy-Paste Friendly** - All code examples are complete and ready to use
219+
4. **Visual Hierarchy** - Color-coded sections, clear headings, proper spacing
220+
5. **Responsive** - Mobile-first design that works on all screen sizes
221+
222+
## Color Scheme
223+
224+
- **Primary:** `#6366f1` (Indigo)
225+
- **Secondary:** `#10b981` (Green)
226+
- **Success:** `#10b981`
227+
- **Warning:** `#f59e0b`
228+
- **Error:** `#ef4444`
229+
- **Info:** `#3b82f6`
230+
231+
## Contributing to Documentation
232+
233+
When adding new pages:
234+
235+
1. Create the page component in `src/pages/`
236+
2. Add the route in `src/App.jsx`
237+
3. Add navigation link in `src/components/Layout/Layout.jsx`
238+
4. Follow existing patterns for consistency
239+
5. Include code examples with syntax highlighting
240+
6. Add alerts for important notes
241+
7. Link to related pages
242+
243+
### Code Example Template
244+
245+
```jsx
246+
import CodeBlock from '../components/CodeBlock/CodeBlock';
247+
248+
const example = `// Your C# code here
249+
public record MyState(int Value)
250+
{
251+
public MyState Increment() => this with { Value = Value + 1 };
252+
}`;
253+
254+
<CodeBlock code={example} title="MyState.cs" />
255+
```
256+
257+
### Alert Template
258+
259+
```jsx
260+
import Alert from '../components/Alert/Alert';
261+
262+
<Alert type="info" title="Pro Tip">
263+
Your helpful message here
264+
</Alert>
265+
```
266+
267+
## Performance
268+
269+
The documentation site is optimized for performance:
270+
271+
- Code splitting via React Router
272+
- Lazy loading of heavy components
273+
- Optimized CSS with CSS variables
274+
- Minimal external dependencies
275+
- Fast Vite build process
276+
277+
## Browser Support
278+
279+
- Chrome (latest)
280+
- Firefox (latest)
281+
- Safari (latest)
282+
- Edge (latest)
283+
284+
## License
285+
286+
MIT © EasyAppDev
287+
288+
## Support
289+
290+
For issues or questions:
291+
- **Library Issues:** [GitHub Issues](https://github.com/mashrulhaque/EasyAppDev.Blazor.Store/issues)
292+
- **Documentation Issues:** Open an issue with the `documentation` label
293+
- **Main Repository:** [EasyAppDev.Blazor.Store](https://github.com/mashrulhaque/EasyAppDev.Blazor.Store)
294+
- **NuGet Package:** [EasyAppDev.Blazor.Store](https://www.nuget.org/packages/EasyAppDev.Blazor.Store/)
295+
296+
---
297+
298+
**Built with ❤️ for the Blazor community**

‎docs-site-react-backup/index.html‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>EasyAppDev.Blazor.Store - Documentation</title>
8+
<meta name="description" content="State management for Blazor that feels natural, type-safe, and delightfully simple." />
9+
10+
<!-- Start Single Page Apps for GitHub Pages -->
11+
<script>
12+
// Single Page Apps for GitHub Pages
13+
// https://github.com/rafgraph/spa-github-pages
14+
// This script checks to see if a redirect is present in the query string,
15+
// converts it back to the correct url and adds it to the
16+
// browser's history using window.history.replaceState(...),
17+
// which won't cause the browser to attempt to load the new url.
18+
// When the single page app is loaded further down in this file,
19+
// the correct url will be waiting in the browser's history for
20+
// the single page app to route accordingly.
21+
(function(l) {
22+
if (l.search[1] === '/' ) {
23+
var decoded = l.search.slice(1).split('&').map(function(s) {
24+
return s.replace(/~and~/g, '&')
25+
}).join('?');
26+
window.history.replaceState(null, null,
27+
l.pathname.slice(0, -1) + decoded + l.hash
28+
);
29+
}
30+
}(window.location))
31+
</script>
32+
<!-- End Single Page Apps for GitHub Pages -->
33+
</head>
34+
<body>
35+
<div id="root"></div>
36+
<script type="module" src="/src/main.jsx"></script>
37+
</body>
38+
</html>

docs-site/package-lock.json renamed to docs-site-react-backup/package-lock.json

File renamed without changes.

docs-site/package.json renamed to docs-site-react-backup/package.json

File renamed without changes.

docs-site/public/.nojekyll renamed to docs-site-react-backup/public/.nojekyll

File renamed without changes.

0 commit comments

Comments
 (0)