Slawomir Koszewski
c09e545637
- React-based web application for testing JMESPath expressions - macOS-first containerization with Apple container command - Bootstrap UI with real-time evaluation - GitHub Actions CI/CD pipeline - Docker fallback support - Comprehensive documentation and development scripts
143 lines
3.6 KiB
Markdown
143 lines
3.6 KiB
Markdown
# Development Guide
|
|
|
|
## Quick Start Commands
|
|
|
|
### macOS Development (Recommended)
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start macOS-optimized development server
|
|
npm run dev
|
|
|
|
# Build with macOS toolset (Apple container + Docker fallback)
|
|
npm run build:macos
|
|
|
|
# Container operations (macOS)
|
|
npm run container:build
|
|
npm run container:run
|
|
```
|
|
|
|
### Traditional Commands
|
|
|
|
```bash
|
|
# Start development server (with hot reload)
|
|
npm start
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Run tests
|
|
npm test
|
|
|
|
# Serve production build locally
|
|
npm run serve
|
|
```
|
|
|
|
## Container Commands
|
|
|
|
### Apple Container (Primary - macOS)
|
|
|
|
```bash
|
|
# Build container with Apple's container command
|
|
container build -t jmespath-playground .
|
|
|
|
# Run container
|
|
container run -p 3000:3000 jmespath-playground
|
|
|
|
# Using Containerfile (Apple's format)
|
|
container build -f Containerfile -t jmespath-playground .
|
|
```
|
|
|
|
### Docker (Fallback)
|
|
|
|
```bash
|
|
# Build Docker container
|
|
docker build -t jmespath-playground .
|
|
|
|
# Run Docker container
|
|
docker run -p 3000:3000 jmespath-playground
|
|
|
|
# Development with Docker Compose
|
|
docker-compose --profile dev up jmespath-playground-dev
|
|
|
|
# Production with Docker Compose
|
|
docker-compose up jmespath-playground
|
|
```
|
|
|
|
## Project Structure Overview
|
|
|
|
```
|
|
src/
|
|
├── App.js # Main component with JMESPath logic
|
|
├── App.css # App-specific styles
|
|
├── App.test.js # Basic tests
|
|
├── index.js # React entry point
|
|
├── index.css # Global styles and Bootstrap overrides
|
|
└── setupTests.js # Test configuration
|
|
```
|
|
|
|
## Key Features Implemented
|
|
|
|
1. **Real-time JMESPath Evaluation**: Uses the `jmespath` library to evaluate expressions as user types
|
|
2. **JSON Validation**: Parses and validates JSON input with error reporting
|
|
3. **Bootstrap UI**: Responsive layout with cards, buttons, and form controls
|
|
4. **Error Handling**: Clear error messages for both JSON and JMESPath syntax issues
|
|
5. **Sample Data**: Pre-loaded examples with "Load Sample" button
|
|
6. **JSON Formatting**: "Format JSON" button to prettify JSON input
|
|
7. **Clear Function**: "Clear All" button to reset all inputs
|
|
|
|
## Component Architecture
|
|
|
|
The main `App.js` component manages:
|
|
- State for JMESPath expression, JSON data, results, and errors
|
|
- Auto-evaluation using `useEffect` when inputs change
|
|
- Error handling for both JSON parsing and JMESPath evaluation
|
|
- UI event handlers for buttons and input changes
|
|
|
|
## Styling
|
|
|
|
- Bootstrap 5.3.2 for responsive grid and components
|
|
- Custom CSS for enhanced UX (color coding, hover effects)
|
|
- Gradient header with professional appearance
|
|
- Color-coded input areas (yellow for JMESPath, green for JSON, blue for results)
|
|
|
|
## Browser Compatibility
|
|
|
|
Built with React 18 and targets:
|
|
- Modern evergreen browsers
|
|
- Node.js 24 LTS compatibility
|
|
- Mobile-responsive design
|
|
|
|
## CI/CD Pipeline
|
|
|
|
### GitHub Actions Workflow
|
|
|
|
The project includes automated container building via GitHub Actions:
|
|
|
|
**Triggers:**
|
|
- Push to `main` or `develop` branches
|
|
- Changes in `src/`, `public/`, `package*.json`, or container files
|
|
- Pull requests to `main` branch
|
|
|
|
**Pipeline Steps:**
|
|
1. Checkout code and setup Node.js 24 LTS
|
|
2. Install dependencies with npm ci
|
|
3. Run test suite with coverage
|
|
4. Build React production bundle
|
|
5. Build and test Docker container
|
|
6. Upload build artifacts
|
|
7. Create multi-platform images (main branch only)
|
|
|
|
**Local Testing:**
|
|
```bash
|
|
# Test the same steps locally
|
|
npm ci
|
|
npm test -- --coverage --watchAll=false
|
|
npm run build
|
|
npm run docker:build
|
|
npm run docker:run
|
|
```
|
|
|
|
The workflow uses Docker in the GitHub Actions environment while maintaining compatibility with the project's macOS-first development approach. |