Joakim
ca3df47451
Major Architecture Improvements: - Separate JavaScript library (lib/) with proper build system - Go CLI with embedded library using go:embed - Hot reload development with Air integration - Library + CLI build pipeline with npm run build Code Cleanup: - Remove obsolete assets (insertr-cli/assets/editor/) - Clean up package.json metadata and dependencies - Update .gitignore for new architecture - Remove unused 'marked' dependency New Documentation: - Add comprehensive TODO.md with feature gap analysis - Document critical gaps between prototype and current library - Create phased implementation plan for feature parity - Update DEVELOPMENT.md with hot reload workflow - Add LIBRARY.md documenting new architecture Hot Reload System: - Air watches both Go CLI and JavaScript library - Library changes trigger: rebuild → copy → CLI rebuild → serve - Seamless development experience across full stack Next Steps: - Current library is basic proof-of-concept (prompt() editing) - Archived prototype has production-ready features - Phase 1 focuses on professional forms and authentication - Phase 2 adds validation and content persistence
215 lines
7.4 KiB
Markdown
215 lines
7.4 KiB
Markdown
# Insertr Development Guide
|
|
|
|
## Quick Start
|
|
|
|
### Full-Stack Development (Recommended)
|
|
1. **Install dependencies**:
|
|
```bash
|
|
npm install # Root project dependencies
|
|
cd lib && npm install # Library dependencies
|
|
```
|
|
|
|
2. **Start hot reload development**:
|
|
```bash
|
|
cd insertr-cli && air # Starts server with library hot reload
|
|
```
|
|
- Watches both Go CLI changes AND JavaScript library changes
|
|
- Automatically rebuilds library → CLI → serves enhanced content
|
|
- Visit http://localhost:3000 to see results
|
|
|
|
### Library-Only Development
|
|
```bash
|
|
cd lib && npm run watch # Just develop the JavaScript library
|
|
```
|
|
|
|
### Legacy Frontend Development
|
|
```bash
|
|
npm run dev # Legacy live-server (demo-site only)
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Hot Reload Development (Current Phase)
|
|
|
|
**🔥 NEW**: Full-stack hot reload with Air integration!
|
|
|
|
- **Library Source**: `lib/src/` - Independent JavaScript library
|
|
- **CLI Integration**: `insertr-cli/` - Go CLI with embedded library
|
|
- **Demo Site**: `demo-site/` - Test website for enhancement
|
|
- **Automatic Rebuilds**: Changes to JS library trigger full rebuild cycle
|
|
|
|
#### How Hot Reload Works:
|
|
1. Edit JavaScript in `lib/src/`
|
|
2. Air detects changes → Rebuilds library → Copies to CLI → Rebuilds CLI
|
|
3. Enhanced development server serves updated content
|
|
4. Manual browser refresh shows changes
|
|
|
|
### Legacy Frontend Development
|
|
|
|
- **Demo Site**: `demo-site/` contains the prototype website
|
|
- **Core Library**: `demo-site/insertr/insertr.js` - the old prototype library
|
|
- **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
|
|
|
|
#### Modern Development (lib/ + insertr-cli/)
|
|
- **Library Changes**: Edit `lib/src/**/*.js` → Air automatically rebuilds everything
|
|
- **CLI Changes**: Edit Go files in `insertr-cli/` → Air rebuilds and restarts server
|
|
- **Demo Content**: Edit `demo-site/*.html` → Air serves enhanced versions
|
|
- **Hot Reload**: Changes trigger full rebuild cycle (library → CLI → enhanced content)
|
|
|
|
#### Legacy Development (demo-site/)
|
|
- **Live Reload**: The server automatically refreshes when you save changes
|
|
- **JavaScript**: Edit `demo-site/insertr/insertr.js` for prototype functionality
|
|
- **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/
|
|
├── DEVELOPMENT.md # This file
|
|
├── LIBRARY.md # Library architecture documentation
|
|
├── package.json # Root project configuration
|
|
│
|
|
├── lib/ # 🆕 Independent JavaScript Library
|
|
│ ├── src/
|
|
│ │ ├── core/
|
|
│ │ │ ├── insertr.js # Core library functionality
|
|
│ │ │ ├── editor.js # Visual editing interface
|
|
│ │ │ └── api-client.js # Content API client
|
|
│ │ └── index.js # Library entry point
|
|
│ ├── dist/
|
|
│ │ ├── insertr.js # Built library (development)
|
|
│ │ └── insertr.min.js # Built library (production)
|
|
│ ├── package.json # Library dependencies
|
|
│ └── rollup.config.js # Build configuration
|
|
│
|
|
├── insertr-cli/ # 🆕 Go CLI with Embedded Library
|
|
│ ├── pkg/content/
|
|
│ │ ├── assets/ # Embedded library files (auto-copied)
|
|
│ │ ├── library.go # Go embed declarations
|
|
│ │ ├── enhancer.go # HTML enhancement orchestrator
|
|
│ │ ├── injector.go # Content injection logic
|
|
│ │ └── ...
|
|
│ ├── scripts/
|
|
│ │ └── rebuild-library.sh # Air helper script
|
|
│ ├── .air.toml # Hot reload configuration
|
|
│ └── insertr # Built CLI executable
|
|
│
|
|
├── demo-site/ # Test website for enhancement
|
|
│ ├── index.html # Demo homepage
|
|
│ ├── about.html # Demo about page
|
|
│ └── assets/style.css # Demo site styling
|
|
│
|
|
└── scripts/
|
|
└── build.js # Integrated build script
|
|
```
|
|
|
|
## Development Scripts
|
|
|
|
### Root Scripts
|
|
- `npm run build` - Build library + CLI with embedded assets
|
|
- `npm run dev` - Legacy live-server (demo-site only)
|
|
|
|
### Library Scripts (cd lib/)
|
|
- `npm run build` - Build library to dist/
|
|
- `npm run watch` - Watch and rebuild library on changes
|
|
|
|
### CLI Scripts (cd insertr-cli/)
|
|
- `air` - 🔥 Hot reload server (library + CLI + enhanced content)
|
|
- `go build -o insertr` - Manual CLI build
|
|
- `./insertr enhance <dir>` - Enhance static site
|
|
- `./insertr servedev <dir>` - Development server with enhancement
|
|
|
|
### Hot Reload Workflow
|
|
```bash
|
|
cd insertr-cli && air # Start hot reload development
|
|
# Edit lib/src/**/*.js # Air detects → rebuilds → serves
|
|
# Edit cmd/**/*.go # Air detects → rebuilds → serves
|
|
# Edit ../demo-site/ # Air serves enhanced versions
|
|
```
|
|
|
|
## 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` |