195 lines
4.6 KiB
Markdown
195 lines
4.6 KiB
Markdown
# Frappe React Frontend
|
|
|
|
A modern React frontend application built with TypeScript, Vite, and TailwindCSS that connects to your existing Frappe backend.
|
|
|
|
## Features
|
|
|
|
- 🔐 **Authentication**: Seamless integration with Frappe's authentication system
|
|
- 🎨 **Modern UI**: Beautiful, responsive interface built with TailwindCSS
|
|
- 🚀 **Fast Development**: Hot module replacement with Vite
|
|
- 📱 **Mobile Ready**: Responsive design that works on all devices
|
|
- 🔌 **API Integration**: Comprehensive API client for Frappe backend
|
|
- 🛡️ **Type Safety**: Full TypeScript support
|
|
- 🧭 **Routing**: Client-side routing with React Router
|
|
|
|
## Tech Stack
|
|
|
|
- **Frontend**: React 19 + TypeScript + Vite
|
|
- **Styling**: TailwindCSS 4
|
|
- **Routing**: React Router DOM
|
|
- **HTTP Client**: Axios
|
|
- **Backend**: Frappe Framework (Python)
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- npm or yarn
|
|
- Running Frappe backend
|
|
|
|
### Installation
|
|
|
|
1. Clone or download this project
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Configure environment variables:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your Frappe backend details
|
|
```
|
|
|
|
4. Start development server:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
5. Open [http://localhost:3000](http://localhost:3000) in your browser
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── api/
|
|
│ └── frappeClient.ts # API client for Frappe backend
|
|
├── pages/
|
|
│ ├── Login.tsx # Login page
|
|
│ ├── Dashboard.tsx # Dashboard page
|
|
│ └── UsersList.tsx # Users list page
|
|
├── components/ # Reusable React components
|
|
├── hooks/ # Custom React hooks
|
|
├── types/ # TypeScript type definitions
|
|
├── utils/ # Utility functions
|
|
├── App.tsx # Main app component
|
|
└── main.tsx # App entry point
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
Create a `.env` file in the root directory:
|
|
|
|
```bash
|
|
# Frappe Backend Configuration
|
|
VITE_FRAPPE_BASE_URL=http://localhost:8000
|
|
VITE_FRAPPE_SITE_NAME=your_site_name
|
|
|
|
# Development Configuration
|
|
VITE_DEV_MODE=true
|
|
VITE_API_TIMEOUT=10000
|
|
```
|
|
|
|
### Frappe Backend Setup
|
|
|
|
1. Add the custom API endpoints to your Frappe app (see `python_api_examples.py`)
|
|
2. Restart your Frappe backend
|
|
3. Ensure CORS is configured for your frontend domain
|
|
|
|
## Available Scripts
|
|
|
|
- `npm run dev` - Start development server
|
|
- `npm run build` - Build for production
|
|
- `npm run preview` - Preview production build
|
|
- `npm run lint` - Run ESLint
|
|
|
|
## API Integration
|
|
|
|
The app includes a comprehensive API client (`frappeClient.ts`) that handles:
|
|
|
|
- Authentication (login/logout)
|
|
- DocType operations (CRUD)
|
|
- File uploads
|
|
- Error handling
|
|
- Session management
|
|
|
|
### Example Usage
|
|
|
|
```typescript
|
|
import frappeAPI from './api/frappeClient';
|
|
|
|
// Login
|
|
const user = await frappeAPI.login({ usr: 'username', pwd: 'password' });
|
|
|
|
// Get records
|
|
const users = await frappeAPI.getDocTypeRecords('User');
|
|
|
|
// Create record
|
|
const newUser = await frappeAPI.createDocTypeRecord('User', {
|
|
email: 'user@example.com',
|
|
first_name: 'John',
|
|
last_name: 'Doe'
|
|
});
|
|
```
|
|
|
|
## Deployment
|
|
|
|
See [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) for detailed deployment instructions.
|
|
|
|
### Quick Deployment
|
|
|
|
1. Build the app:
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
2. Copy `dist/` contents to your Frappe app's `public/` folder
|
|
|
|
3. Restart Frappe:
|
|
```bash
|
|
bench restart
|
|
```
|
|
|
|
## Customization
|
|
|
|
### Adding New Pages
|
|
|
|
1. Create a new component in `src/pages/`
|
|
2. Add route in `src/App.tsx`
|
|
3. Update navigation as needed
|
|
|
|
### Styling
|
|
|
|
The app uses TailwindCSS. You can:
|
|
- Modify `tailwind.config.js` for custom themes
|
|
- Add custom CSS in `src/index.css`
|
|
- Use Tailwind utility classes in components
|
|
|
|
### API Endpoints
|
|
|
|
Add new API methods in `src/api/frappeClient.ts` and corresponding Python endpoints in your Frappe app.
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **CORS Errors**: Check Frappe CORS configuration
|
|
2. **Authentication Issues**: Verify session cookies
|
|
3. **API Not Found**: Ensure API files are deployed and Frappe is restarted
|
|
4. **Build Errors**: Check Node.js version compatibility
|
|
|
|
### Debug Mode
|
|
|
|
Enable debug logging by setting `VITE_DEV_MODE=true` in your `.env` file.
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Test thoroughly
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License.
|
|
|
|
## Support
|
|
|
|
For issues and questions:
|
|
1. Check the [Deployment Guide](./DEPLOYMENT_GUIDE.md)
|
|
2. Review the [Frappe Documentation](https://frappeframework.com/docs)
|
|
3. Open an issue in this repository |