@gasket/template-api-express 1.0.0 → 7.0.1
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/README.md +128 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Gasket API Express Template
|
|
2
|
+
|
|
3
|
+
A production-ready TypeScript API template built with Gasket and Express.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
This template provides a minimal, well-structured starting point for building RESTful APIs using:
|
|
8
|
+
|
|
9
|
+
- **Express** - Fast, unopinionated web framework for Node.js
|
|
10
|
+
- **TypeScript** - Type-safe development with modern JavaScript features
|
|
11
|
+
- **Gasket** - Plugin architecture for extensible applications
|
|
12
|
+
- **Swagger/OpenAPI** - Automatic API documentation generation
|
|
13
|
+
- **Winston** - Production-grade logging
|
|
14
|
+
- **Vitest** - Lightning-fast unit testing
|
|
15
|
+
|
|
16
|
+
## Features
|
|
17
|
+
|
|
18
|
+
- ✅ **TypeScript configuration** with ES modules support
|
|
19
|
+
- ✅ **Express server** with middleware pipeline
|
|
20
|
+
- ✅ **Swagger documentation** auto-generated from JSDoc comments
|
|
21
|
+
- ✅ **Structured logging** with Winston
|
|
22
|
+
- ✅ **Testing setup** with Vitest and coverage reporting
|
|
23
|
+
- ✅ **Development server** with hot reloading via tsx
|
|
24
|
+
- ✅ **Build pipeline** for production deployment
|
|
25
|
+
- ✅ **ESLint configuration** with GoDaddy style guide
|
|
26
|
+
|
|
27
|
+
## Quick Start
|
|
28
|
+
|
|
29
|
+
Create a new API project using this template:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npx create-gasket-app@latest my-api --template @gasket/template-api-express
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Project Structure
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
my-api/
|
|
39
|
+
├── gasket.ts # Gasket configuration
|
|
40
|
+
├── server.ts # Server entry point
|
|
41
|
+
├── plugins/ # Custom Gasket plugins
|
|
42
|
+
│ └── routes-plugin.ts # API route definitions
|
|
43
|
+
├── swagger.json # OpenAPI schema (generated)
|
|
44
|
+
├── test/ # Test files
|
|
45
|
+
├── tsconfig.json # TypeScript configuration
|
|
46
|
+
└── dist/ # Built JavaScript (after npm run build)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Available Scripts
|
|
50
|
+
|
|
51
|
+
| Script | Description |
|
|
52
|
+
|--------|-------------|
|
|
53
|
+
| `npm run local` | Start development server with hot reload |
|
|
54
|
+
| `npm run build` | Build TypeScript to JavaScript |
|
|
55
|
+
| `npm run start` | Start production server from built files |
|
|
56
|
+
| `npm run test` | Run unit tests |
|
|
57
|
+
| `npm run test:watch` | Run tests in watch mode |
|
|
58
|
+
| `npm run test:coverage` | Run tests with coverage report |
|
|
59
|
+
| `npm run docs` | Generate and serve API documentation |
|
|
60
|
+
| `npm run lint` | Check code style and quality |
|
|
61
|
+
|
|
62
|
+
## API Routes
|
|
63
|
+
|
|
64
|
+
The template includes a sample route to get you started:
|
|
65
|
+
|
|
66
|
+
### `GET /default`
|
|
67
|
+
|
|
68
|
+
Returns a welcome message.
|
|
69
|
+
|
|
70
|
+
**Response:**
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"message": "Welcome to your default route..."
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Adding New Routes
|
|
78
|
+
|
|
79
|
+
Define routes in `plugins/routes-plugin.ts` using the `express` lifecycle:
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
export default {
|
|
83
|
+
name: 'routes-plugin',
|
|
84
|
+
hooks: {
|
|
85
|
+
express(gasket, app) {
|
|
86
|
+
/**
|
|
87
|
+
* @swagger
|
|
88
|
+
* /users:
|
|
89
|
+
* get:
|
|
90
|
+
* summary: Get all users
|
|
91
|
+
* responses:
|
|
92
|
+
* 200:
|
|
93
|
+
* description: List of users
|
|
94
|
+
*/
|
|
95
|
+
app.get('/users', (req, res) => {
|
|
96
|
+
res.json({ users: [] });
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
};
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Documentation
|
|
104
|
+
|
|
105
|
+
Run `npm run docs` to generate interactive API documentation using Swagger UI. The docs are automatically generated from JSDoc comments in your route handlers.
|
|
106
|
+
|
|
107
|
+
## Testing
|
|
108
|
+
|
|
109
|
+
The template includes Vitest for testing. Write tests in the `test/` directory:
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
import { describe, it, expect } from 'vitest';
|
|
113
|
+
|
|
114
|
+
describe('API Routes', () => {
|
|
115
|
+
it('should return welcome message', () => {
|
|
116
|
+
// Your test code here
|
|
117
|
+
});
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Next Steps
|
|
122
|
+
|
|
123
|
+
- Add your API routes in `plugins/routes-plugin.ts`
|
|
124
|
+
- Configure database connections and models
|
|
125
|
+
- Set up authentication and authorization
|
|
126
|
+
- Add input validation and error handling
|
|
127
|
+
- Configure environment-specific settings
|
|
128
|
+
- Set up CI/CD pipeline
|