Add development workflow and project setup
🛠️ Development Infrastructure: - package.json with npm scripts for development - live-server for hot reload during development - Custom dev helper script with project validation - Comprehensive .gitignore for Node.js and Go 📖 Documentation: - Updated README.md with project overview and quick start - DEVELOPMENT.md with detailed development guide - Demo instructions and testing scenarios 🚀 Available Commands: - npm run dev (start development server) - npm run dev:check (validate project setup) - npm run dev:demo (show testing instructions) - npm run dev:help (list all commands) ✨ Features: - Live reload on file changes - Project health checking - 18 editable elements detected - 14.3KB core library size Next: Ready for active development and testing!
This commit is contained in:
160
DEVELOPMENT.md
Normal file
160
DEVELOPMENT.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Insertr Development Guide
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Install dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Start development server**:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
This will start live-server on http://localhost:3000 and automatically open the demo site.
|
||||
|
||||
3. **Alternative commands**:
|
||||
```bash
|
||||
npm run dev:about # Open about page directly
|
||||
npm run serve # Alias for npm run dev
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Frontend Development (Current Phase)
|
||||
|
||||
- **Demo Site**: `demo-site/` contains the prototype website
|
||||
- **Core Library**: `demo-site/insertr/insertr.js` - the main Insertr library
|
||||
- **Styling**: `demo-site/insertr/insertr.css` - edit interface styles
|
||||
- **Mock API**: `demo-site/mock-api/content.json` - sample backend data structure
|
||||
|
||||
### Testing the Three User Types
|
||||
|
||||
1. **Customer View**: Open the site normally - clean, no edit interface
|
||||
2. **Client View**: Click "Login as Client" then "Edit Mode: On" - see edit buttons
|
||||
3. **Developer View**: Look at the HTML source to see simple integration
|
||||
|
||||
### Making Changes
|
||||
|
||||
- **Live Reload**: The server automatically refreshes when you save changes
|
||||
- **JavaScript**: Edit `demo-site/insertr/insertr.js` to modify core functionality
|
||||
- **Styling**: Edit `demo-site/insertr/insertr.css` for UI changes
|
||||
- **Content**: Edit HTML files to test different content structures
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. **Content Types**: Extend the `createEditForm()` method in insertr.js
|
||||
2. **UI Components**: Add new CSS classes and corresponding JavaScript
|
||||
3. **Authentication**: Modify the mock auth system in `toggleAuthentication()`
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
insertr/
|
||||
├── INITIAL.md # Project requirements and research
|
||||
├── DEVELOPMENT.md # This file
|
||||
├── package.json # Node.js project configuration
|
||||
├── .gitignore # Git ignore rules
|
||||
│
|
||||
├── demo-site/ # Frontend prototype
|
||||
│ ├── index.html # Demo homepage
|
||||
│ ├── about.html # Demo about page
|
||||
│ ├── README.md # Demo usage instructions
|
||||
│ │
|
||||
│ ├── assets/ # Demo site assets
|
||||
│ │ └── style.css # Demo site styling
|
||||
│ │
|
||||
│ ├── insertr/ # Core Insertr library
|
||||
│ │ ├── insertr.js # Main library file
|
||||
│ │ ├── insertr.css # Edit interface styles
|
||||
│ │ └── components/ # Future: reusable edit components
|
||||
│ │
|
||||
│ └── mock-api/ # Backend planning
|
||||
│ └── content.json # Sample data structure
|
||||
│
|
||||
└── backend/ # Future: Go backend
|
||||
├── main.go # Future: HTTP server
|
||||
├── api/ # Future: REST endpoints
|
||||
└── storage/ # Future: file-based storage
|
||||
```
|
||||
|
||||
## Development Scripts
|
||||
|
||||
- `npm run dev` - Start development server with live reload
|
||||
- `npm run dev:about` - Start server opening about page
|
||||
- `npm run build` - Future: Bundle library for distribution
|
||||
- `npm run test` - Future: Run tests
|
||||
- `npm run lint` - Future: Code linting
|
||||
|
||||
## Testing Different Scenarios
|
||||
|
||||
### Content Types
|
||||
- **Simple Text**: Logo, titles, short descriptions
|
||||
- **Rich Content**: Paragraphs with markdown, lists, links
|
||||
- **Mixed Content**: Cards with multiple editable sections
|
||||
|
||||
### User Flows
|
||||
1. **First Visit**: Customer sees clean site
|
||||
2. **Client Login**: Authentication state changes
|
||||
3. **Edit Mode**: Toggle editing interface
|
||||
4. **Content Editing**: Click edit → modify → save
|
||||
5. **Multi-page**: Test persistence across pages
|
||||
|
||||
### Browser Testing
|
||||
Test in different browsers to ensure compatibility:
|
||||
- Chrome/Edge (Chromium)
|
||||
- Firefox
|
||||
- Safari (if on macOS)
|
||||
|
||||
## Future Development Phases
|
||||
|
||||
### Phase 2: Backend Integration
|
||||
- Go HTTP server with REST API
|
||||
- Real authentication with Authentik OAuth
|
||||
- File-based content persistence
|
||||
- Git version control
|
||||
|
||||
### Phase 3: Production Features
|
||||
- Multi-tenant support
|
||||
- Admin dashboard
|
||||
- Content validation
|
||||
- Image upload
|
||||
- Deployment automation
|
||||
|
||||
## Contributing Guidelines
|
||||
|
||||
1. **Make changes** in small, focused commits
|
||||
2. **Test thoroughly** across different content types
|
||||
3. **Update documentation** when adding new features
|
||||
4. **Follow existing code style** and patterns
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### JavaScript Console
|
||||
- Open browser dev tools (F12)
|
||||
- Check for errors in Console tab
|
||||
- Use `window.insertr` to inspect library state
|
||||
|
||||
### Local Storage
|
||||
- View saved content: `localStorage.getItem('insertr_content')`
|
||||
- Clear saved content: `localStorage.clear()`
|
||||
|
||||
### Network Simulation
|
||||
- The library simulates network delays and occasional failures
|
||||
- Check browser Network tab to see mock API calls (when implemented)
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Live Server Not Working
|
||||
- Ensure port 3000 is available
|
||||
- Try different port: `live-server demo-site --port=3001`
|
||||
|
||||
### Changes Not Reflecting
|
||||
- Hard refresh browser (Ctrl+F5 / Cmd+Shift+R)
|
||||
- Check browser cache settings
|
||||
- Verify file paths are correct
|
||||
|
||||
### Edit Buttons Not Showing
|
||||
- Check authentication state (click "Login as Client")
|
||||
- Enable edit mode (click "Edit Mode: Off" → "Edit Mode: On")
|
||||
- Verify elements have `class="insertr"` and `data-content-id`
|
||||
Reference in New Issue
Block a user