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
138 lines
4.2 KiB
Markdown
138 lines
4.2 KiB
Markdown
# Insertr Library Architecture
|
|
|
|
## Overview
|
|
|
|
Insertr now uses a proper separation between the JavaScript library and Go CLI, following the "Tailwind of CMS" philosophy where the library can be developed independently and embedded into the CLI at build time.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
insertr/
|
|
├── lib/ # Independent JavaScript library
|
|
│ ├── src/
|
|
│ │ ├── core/
|
|
│ │ │ ├── insertr.js # Main library core
|
|
│ │ │ ├── editor.js # Visual editing functionality
|
|
│ │ │ └── api-client.js # Content API client
|
|
│ │ └── index.js # Library entry point
|
|
│ ├── dist/
|
|
│ │ ├── insertr.js # Built library (dev)
|
|
│ │ └── insertr.min.js # Built library (production)
|
|
│ ├── package.json
|
|
│ └── rollup.config.js # Build configuration
|
|
├── insertr-cli/ # Go CLI with embedded library
|
|
│ ├── pkg/content/
|
|
│ │ ├── assets/ # Embedded library files
|
|
│ │ │ ├── insertr.js # From lib/dist/
|
|
│ │ │ └── insertr.min.js # From lib/dist/
|
|
│ │ ├── library.go # Go embed declarations
|
|
│ │ ├── injector.go # HTML injection logic
|
|
│ │ └── ...
|
|
│ └── insertr # Built CLI executable
|
|
└── scripts/
|
|
└── build.js # Integrated build script
|
|
```
|
|
|
|
## Build Process
|
|
|
|
### 1. Library Development (`lib/`)
|
|
```bash
|
|
cd lib
|
|
npm install
|
|
npm run build # Creates dist/insertr.js and dist/insertr.min.js
|
|
npm run watch # Development mode with file watching
|
|
```
|
|
|
|
### 2. CLI Integration (`insertr-cli/`)
|
|
The CLI uses Go's `//go:embed` directive to embed the built library:
|
|
|
|
```go
|
|
//go:embed assets/insertr.min.js
|
|
var libraryMinJS string
|
|
|
|
//go:embed assets/insertr.js
|
|
var libraryJS string
|
|
```
|
|
|
|
### 3. Integrated Build (Root)
|
|
```bash
|
|
npm run build # Builds both library AND CLI with embedded assets
|
|
```
|
|
|
|
This script:
|
|
1. Builds the JavaScript library (`lib/dist/`)
|
|
2. Copies built assets to CLI (`insertr-cli/pkg/content/assets/`)
|
|
3. Builds Go CLI with embedded library
|
|
|
|
## Library Features
|
|
|
|
### Core Functionality (`src/core/insertr.js`)
|
|
- Element discovery: `findEnhancedElements()`
|
|
- Metadata extraction: `getElementMetadata()`
|
|
- Element management: `getAllElements()`
|
|
|
|
### Visual Editor (`src/core/editor.js`)
|
|
- Hover effects and visual indicators
|
|
- Click-to-edit functionality
|
|
- Content update handling
|
|
- Dynamic style injection
|
|
|
|
### API Client (`src/core/api-client.js`)
|
|
- RESTful content API communication
|
|
- CRUD operations for content
|
|
- Error handling and fallbacks
|
|
|
|
## CLI Integration
|
|
|
|
### Asset Embedding (`pkg/content/library.go`)
|
|
```go
|
|
func GetLibraryScript(minified bool) string {
|
|
if minified {
|
|
return libraryMinJS // Production: smaller file size
|
|
}
|
|
return libraryJS // Development: readable code
|
|
}
|
|
```
|
|
|
|
### HTML Injection (`pkg/content/injector.go`)
|
|
```go
|
|
func (i *Injector) InjectEditorAssets(doc *html.Node, isDevelopment bool, libraryScript string) {
|
|
// Injects the embedded library as inline <script> tag
|
|
}
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Library Development
|
|
```bash
|
|
cd lib
|
|
npm run watch # Auto-rebuild on changes
|
|
```
|
|
|
|
### CLI Development
|
|
```bash
|
|
cd insertr-cli
|
|
go build -o insertr
|
|
./insertr enhance ../demo-site/
|
|
```
|
|
|
|
### Full Integration Testing
|
|
```bash
|
|
npm run build # Builds library + CLI
|
|
cd insertr-cli && ./insertr enhance ../demo-site/
|
|
```
|
|
|
|
## Benefits
|
|
|
|
1. **Independent Development**: Library can be developed and tested separately
|
|
2. **Version Control**: CLI embeds specific library version at build time
|
|
3. **Zero Dependencies**: Enhanced HTML contains everything needed to run
|
|
4. **CDN Ready**: Library can be served from CDN in production
|
|
5. **Development Friendly**: Unminified version for debugging
|
|
|
|
## Future Enhancements
|
|
|
|
- **CDN Integration**: Support for `<script src="https://cdn.insertr.dev/v1.0.0/insertr.min.js">`
|
|
- **Library Hot Reload**: Auto-rebuild CLI when library changes
|
|
- **Version Sync**: Automated version bumping across library and CLI
|
|
- **Production Optimization**: Tree-shaking and custom builds |