README and UI README from the robot with project details
This commit is contained in:
199
README.md
199
README.md
@@ -1,2 +1,199 @@
|
||||
# glancr
|
||||
A Markdown documentation viewer written in Go and React.
|
||||
|
||||
A modern Markdown documentation viewer built with Go and React. **glancr** provides a clean, fast interface for browsing and viewing Markdown documentation with live reload capabilities during development.
|
||||
|
||||
## Features
|
||||
|
||||
- 🚀 **Fast & Lightweight** - Single binary deployment with embedded assets
|
||||
- 📝 **Markdown Rendering** - Beautiful rendering of Markdown documents
|
||||
- 🔄 **Live Development** - Hot reload during development
|
||||
- 🎨 **Modern UI** - Clean, responsive React-based interface
|
||||
- 📱 **Mobile Friendly** - Responsive design that works on all devices
|
||||
- 🔧 **Easy Setup** - Simple development and deployment workflow
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Go** 1.19+
|
||||
- **Node.js** 18+ and npm
|
||||
- **Git**
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Development
|
||||
|
||||
1. **Clone the repository**
|
||||
```bash
|
||||
git clone https://github.com/smjklake/glancr.git
|
||||
cd glancr
|
||||
```
|
||||
|
||||
2. **Install dependencies**
|
||||
```bash
|
||||
make deps
|
||||
```
|
||||
|
||||
3. **Start development servers**
|
||||
```bash
|
||||
make dev
|
||||
```
|
||||
|
||||
This will start:
|
||||
- Frontend dev server at http://localhost:5173
|
||||
- Backend API server at http://localhost:8080
|
||||
|
||||
### Production Build
|
||||
|
||||
1. **Build for production**
|
||||
```bash
|
||||
make build-prod
|
||||
```
|
||||
|
||||
2. **Run the binary**
|
||||
```bash
|
||||
./dist/glancr
|
||||
```
|
||||
|
||||
The application will be available at http://localhost:8080
|
||||
|
||||
## Available Commands
|
||||
|
||||
### Development
|
||||
- `make dev` - Start development environment with live reload
|
||||
- `make build-dev` - Build development version (filesystem assets)
|
||||
- `make test` - Run Go tests
|
||||
|
||||
### Production
|
||||
- `make build-prod` - Build production version (embedded assets)
|
||||
- `make release` - Clean build for production release
|
||||
- `make build-cross-prod` - Build for multiple platforms
|
||||
|
||||
### Utilities
|
||||
- `make clean` - Clean build artifacts
|
||||
- `make clean-all` - Deep clean including node_modules
|
||||
- `make deps` - Install all dependencies
|
||||
- `make help` - Show all available commands
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
glancr/
|
||||
├── cmd/
|
||||
│ └── server/ # Application entry point
|
||||
│ └── main.go
|
||||
├── internal/ # Private application code
|
||||
│ ├── auth/ # Authentication logic
|
||||
│ └── fs/ # Asset handling (dev/prod)
|
||||
├── ui/ # React frontend
|
||||
│ ├── src/
|
||||
│ ├── public/
|
||||
│ └── package.json
|
||||
├── dist/ # Build output
|
||||
├── Makefile # Build automation
|
||||
├── dev.sh # Development script
|
||||
└── go.mod # Go module definition
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
**glancr** uses a clean architecture with clear separation between frontend and backend:
|
||||
|
||||
- **Backend (Go)**: Serves the React SPA and provides API endpoints
|
||||
- **Frontend (React)**: Modern TypeScript-based UI with Vite tooling
|
||||
- **Asset Handling**: Development mode serves from filesystem, production embeds assets in binary
|
||||
- **Build System**: Makefile orchestrates both Go and Node.js build processes
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Adding Features
|
||||
|
||||
1. **Backend changes**: Add logic in `internal/` packages
|
||||
2. **Frontend changes**: Modify React components in `ui/src/`
|
||||
3. **API endpoints**: Update server routes in `cmd/server/main.go`
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run Go tests
|
||||
make test
|
||||
|
||||
# Run with production build tags
|
||||
make test-prod
|
||||
|
||||
# Run all tests
|
||||
make test-all
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
The frontend includes:
|
||||
- **ESLint** for code linting
|
||||
- **Prettier** for code formatting
|
||||
- **TypeScript** for type safety
|
||||
|
||||
```bash
|
||||
cd ui
|
||||
npm run lint # Check for linting issues
|
||||
npm run lint:fix # Fix auto-fixable issues
|
||||
npm run format # Format code with Prettier
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Single Binary Deployment
|
||||
|
||||
Build and deploy the production binary:
|
||||
|
||||
```bash
|
||||
make release
|
||||
scp dist/glancr user@server:/path/to/deployment/
|
||||
```
|
||||
|
||||
### Cross-Platform Builds
|
||||
|
||||
Generate binaries for multiple platforms:
|
||||
|
||||
```bash
|
||||
make build-cross-prod
|
||||
```
|
||||
|
||||
Produces:
|
||||
- `glancr-linux-amd64`
|
||||
- `glancr-darwin-amd64`
|
||||
- `glancr-darwin-arm64`
|
||||
- `glancr-windows-amd64.exe`
|
||||
|
||||
## Configuration
|
||||
|
||||
Currently **glancr** runs with minimal configuration. The server starts on port 8080 by default.
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Make your changes
|
||||
4. Run tests (`make test`)
|
||||
5. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
6. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
7. Open a Pull Request
|
||||
|
||||
### Development Guidelines
|
||||
|
||||
- Follow Go conventions and use `gofmt`
|
||||
- Write tests for new functionality
|
||||
- Use TypeScript for frontend development
|
||||
- Run `make lint` before committing
|
||||
- Keep commits atomic and well-described
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Built with [Go](https://golang.org/) and [React](https://reactjs.org/)
|
||||
- Bundled with [Vite](https://vitejs.dev/)
|
||||
- Styled with modern CSS practices
|
||||
|
||||
---
|
||||
|
||||
**glancr** - Making documentation beautiful, one markdown file at a time. ✨
|
||||
@@ -8,5 +8,5 @@ import (
|
||||
)
|
||||
|
||||
func getUIAssets() fs.FS {
|
||||
return os.DirFS("internal/fs/dist")
|
||||
return os.DirFS("ui/dist")
|
||||
}
|
||||
|
||||
279
ui/README.md
279
ui/README.md
@@ -1,54 +1,251 @@
|
||||
# React + TypeScript + Vite
|
||||
# glancr UI
|
||||
|
||||
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
|
||||
The React frontend for **glancr** - a modern Markdown documentation viewer. This UI provides a clean, responsive interface built with React 19, TypeScript, and Vite.
|
||||
|
||||
Currently, two official plugins are available:
|
||||
## Tech Stack
|
||||
|
||||
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
|
||||
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
|
||||
- **React 19** - Latest React with concurrent features
|
||||
- **TypeScript** - Type-safe JavaScript development
|
||||
- **Vite** - Fast build tool and dev server
|
||||
- **ESLint** - Code linting and quality checks
|
||||
- **Prettier** - Code formatting
|
||||
- **CSS3** - Modern styling with CSS custom properties
|
||||
|
||||
## Expanding the ESLint configuration
|
||||
## Prerequisites
|
||||
|
||||
If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
|
||||
- **Node.js** 18+
|
||||
- **npm** (comes with Node.js)
|
||||
|
||||
```js
|
||||
export default tseslint.config({
|
||||
extends: [
|
||||
// Remove ...tseslint.configs.recommended and replace with this
|
||||
...tseslint.configs.recommendedTypeChecked,
|
||||
// Alternatively, use this for stricter rules
|
||||
...tseslint.configs.strictTypeChecked,
|
||||
// Optionally, add this for stylistic rules
|
||||
...tseslint.configs.stylisticTypeChecked,
|
||||
],
|
||||
languageOptions: {
|
||||
// other options...
|
||||
parserOptions: {
|
||||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
## Quick Start
|
||||
|
||||
### Development
|
||||
|
||||
1. **Install dependencies**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Start development server**
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The UI will be available at http://localhost:5173
|
||||
|
||||
3. **Start with backend** (recommended)
|
||||
```bash
|
||||
npm run dev:full
|
||||
```
|
||||
|
||||
This starts both the Vite dev server and the Go backend server.
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Outputs optimized files to `dist/` directory.
|
||||
|
||||
## Available Scripts
|
||||
|
||||
### Development
|
||||
- `npm run dev` - Start Vite dev server only
|
||||
- `npm run dev:full` - Start both frontend and backend servers
|
||||
- `npm run watch` - Build in watch mode
|
||||
|
||||
### Building
|
||||
- `npm run build` - Production build
|
||||
- `npm run preview` - Preview production build locally
|
||||
|
||||
### Code Quality
|
||||
- `npm run lint` - Run ESLint checks
|
||||
- `npm run lint:fix` - Fix auto-fixable ESLint issues
|
||||
- `npm run format` - Format code with Prettier
|
||||
- `npm run format:check` - Check if code is properly formatted
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ui/
|
||||
├── src/
|
||||
│ ├── assets/ # Static assets (images, icons, etc.)
|
||||
│ ├── App.tsx # Main application component
|
||||
│ ├── App.css # Application styles
|
||||
│ ├── main.tsx # Application entry point
|
||||
│ ├── index.css # Global styles
|
||||
│ └── vite-env.d.ts # Vite type definitions
|
||||
├── public/ # Public static files
|
||||
├── dist/ # Build output (generated)
|
||||
├── index.html # HTML template
|
||||
├── package.json # Dependencies and scripts
|
||||
├── vite.config.ts # Vite configuration
|
||||
├── tsconfig.json # TypeScript configuration
|
||||
├── tsconfig.app.json # App-specific TypeScript config
|
||||
├── tsconfig.node.json # Node-specific TypeScript config
|
||||
├── eslint.config.ts # ESLint configuration
|
||||
└── prettier.config.ts # Prettier configuration
|
||||
```
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Style
|
||||
|
||||
- **TypeScript**: Use strict type checking
|
||||
- **Components**: Functional components with hooks
|
||||
- **Naming**: PascalCase for components, camelCase for functions/variables
|
||||
- **Imports**: Use absolute imports when possible
|
||||
|
||||
### File Organization
|
||||
|
||||
As the project grows, consider this structure:
|
||||
|
||||
```
|
||||
src/
|
||||
├── components/ # Reusable UI components
|
||||
│ ├── common/ # Generic components
|
||||
│ └── markdown/ # Markdown-specific components
|
||||
├── hooks/ # Custom React hooks
|
||||
├── types/ # TypeScript type definitions
|
||||
├── utils/ # Utility functions
|
||||
├── styles/ # CSS modules or styled components
|
||||
└── api/ # API client functions
|
||||
```
|
||||
|
||||
### Component Guidelines
|
||||
|
||||
- Use TypeScript interfaces for prop types
|
||||
- Implement proper error boundaries
|
||||
- Follow React best practices for hooks
|
||||
- Use semantic HTML elements
|
||||
- Ensure accessibility (ARIA labels, keyboard navigation)
|
||||
|
||||
Example component structure:
|
||||
```typescript
|
||||
interface MyComponentProps {
|
||||
title: string;
|
||||
onAction?: () => void;
|
||||
}
|
||||
|
||||
export function MyComponent({ title, onAction }: MyComponentProps) {
|
||||
// Component logic here
|
||||
return (
|
||||
<div>
|
||||
<h2>{title}</h2>
|
||||
{/* Component JSX */}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
The frontend communicates with the Go backend through a proxy configuration in `vite.config.ts`:
|
||||
|
||||
```typescript
|
||||
server: {
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:8080',
|
||||
changeOrigin: true,
|
||||
},
|
||||
},
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
|
||||
This allows you to make API calls to `/api/*` endpoints during development, which will be proxied to the Go server.
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import reactX from 'eslint-plugin-react-x'
|
||||
import reactDom from 'eslint-plugin-react-dom'
|
||||
## Environment Variables
|
||||
|
||||
export default tseslint.config({
|
||||
plugins: {
|
||||
// Add the react-x and react-dom plugins
|
||||
'react-x': reactX,
|
||||
'react-dom': reactDom,
|
||||
},
|
||||
rules: {
|
||||
// other rules...
|
||||
// Enable its recommended typescript rules
|
||||
...reactX.configs['recommended-typescript'].rules,
|
||||
...reactDom.configs.recommended.rules,
|
||||
},
|
||||
})
|
||||
Create a `.env.local` file for local environment variables:
|
||||
|
||||
```env
|
||||
VITE_API_BASE_URL=http://localhost:8080
|
||||
```
|
||||
|
||||
Access in code:
|
||||
```typescript
|
||||
const apiUrl = import.meta.env.VITE_API_BASE_URL;
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Currently, no testing framework is configured. Consider adding:
|
||||
|
||||
- **Vitest** - Fast unit testing (Vite-native)
|
||||
- **Testing Library** - React component testing
|
||||
- **Playwright** - End-to-end testing
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **Code Splitting**: Use React.lazy() for route-based splitting
|
||||
- **Bundle Analysis**: Use `npm run build` and analyze bundle size
|
||||
- **Images**: Optimize images and use appropriate formats
|
||||
- **Caching**: Leverage Vite's built-in caching strategies
|
||||
|
||||
## Deployment
|
||||
|
||||
The UI is built and embedded into the Go binary for production. The build process:
|
||||
|
||||
1. `npm run build` creates optimized files in `dist/`
|
||||
2. The Go build process embeds these files using `//go:embed`
|
||||
3. The resulting binary serves the UI as a SPA
|
||||
|
||||
## Browser Support
|
||||
|
||||
- **Modern browsers** with ES2020+ support
|
||||
- **Chrome/Edge** 88+
|
||||
- **Firefox** 84+
|
||||
- **Safari** 14+
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Port already in use**
|
||||
```bash
|
||||
# Kill process using port 5173
|
||||
lsof -ti:5173 | xargs kill -9
|
||||
```
|
||||
|
||||
**Node modules issues**
|
||||
```bash
|
||||
# Clean install
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
**TypeScript errors**
|
||||
```bash
|
||||
# Check TypeScript configuration
|
||||
npx tsc --noEmit
|
||||
```
|
||||
|
||||
### Development Tips
|
||||
|
||||
- Use React DevTools browser extension
|
||||
- Enable Vite's built-in HMR for instant updates
|
||||
- Use TypeScript strict mode for better type safety
|
||||
- Set up your editor with ESLint and Prettier extensions
|
||||
|
||||
## Contributing
|
||||
|
||||
When contributing to the UI:
|
||||
|
||||
1. Follow the established code style
|
||||
2. Add TypeScript types for new components
|
||||
3. Test your changes in both dev and production builds
|
||||
4. Run linting and formatting before committing
|
||||
5. Consider responsive design for all screen sizes
|
||||
|
||||
## Integration with Backend
|
||||
|
||||
The UI is designed to work seamlessly with the Go backend:
|
||||
|
||||
- **Development**: Vite proxy handles API routing
|
||||
- **Production**: Served as static files by Go server
|
||||
- **SPA Routing**: Backend handles client-side routing fallback
|
||||
|
||||
---
|
||||
|
||||
Part of the **glancr** project - making documentation beautiful, one component at a time. ⚛️
|
||||
Reference in New Issue
Block a user