Contributing Guide
Getting Started
Thank you for your interest in contributing to eKuiper Manager. We aim to build the most robust, open-source management interface for LF Edge eKuiper, and your help is vital.
Prerequisites
To set up the development environment, ensure you have the following installed:
- Node.js: v18.17.0 or later
- npm: v9.0.0 or later
- eKuiper Instance: A running instance of eKuiper for testing (alternatively, use the mock scripts provided in the repo).
Local Development Setup
-
Clone the Repository
git clone https://github.com/ankur-paan/ekuiper-manager.git cd ekuiper-manager -
Install Dependencies
npm install -
Environment Configuration Create a
.env.localfile in the root directory. If you plan to contribute to AI features, add your OpenRouter API key:OPENROUTER_API_KEY=your_key_here NEXT_PUBLIC_DEFAULT_EKUIPER_URL=http://localhost:9081 -
Run the Development Server
npm run devOpen http://localhost:3000 with your browser to see the result.
Technical Standards
Code Style
- TypeScript: All new code must be written in TypeScript. Avoid using
anywhere possible; use the interfaces defined insrc/lib/ekuiper/types.ts. - Framework: Next.js 14 (App Router).
- Styling: Tailwind CSS for UI components.
- Linting: Ensure your code passes
npm run lintbefore submitting a PR.
API Proxying
The project uses Next.js Route Handlers to proxy requests to eKuiper instances to avoid CORS issues.
- Client-side calls should use the internal proxy:
/api/connections/[id]/ekuiper/[...path]. - Direct server-side calls should use the
EKuiperClientinDIRECTmode (seesrc/lib/ekuiper/client.ts).
AI Logic & Prompts
When contributing to AI features (located in src/app/api/ai/):
- Robustness: Always implement "Robust JSON extraction" logic to handle AI responses that might include markdown wrappers.
- Rate Limiting: Handle
429status codes gracefully. - System Instructions: Keep prompts focused on "Industrial Automation" contexts as per existing patterns.
Verification & Testing
Before submitting a Pull Request, verify your changes against a live or mock eKuiper instance using the provided scripts.
Running Verification Scripts
We provide scripts to ensure your changes haven't broken the core client logic:
# Check if the OpenAPI spec is reachable and valid
npx ts-node scripts/check-openapi.ts
# Verify core API operations (Streams, Rules, Plugins)
npx ts-node scripts/verify-api.ts
Pull Request Process
- Branching: Create a feature branch from
main(e.g.,feat/rule-editor-updatesorfix/connection-timeout). - Commit Messages: Follow Conventional Commits (e.g.,
feat: add rule topology zoom,fix: handle empty stream lists). - PR Template: Your PR description should include:
- A summary of the changes.
- The issue number being addressed (if applicable).
- Screenshots for UI/UX changes.
- Confirmation that
npm run lintand verification scripts pass.
- Review: At least one maintainer must review and approve the PR before merging.
Project Structure
| Directory | Description |
|-----------|-------------|
| src/app/api | Next.js Route Handlers (AI logic, eKuiper proxy). |
| src/components | Reusable UI components (shadcn/ui based). |
| src/lib/ekuiper | Core API client and TypeScript definitions. |
| src/lib/openrouter | AI provider integration. |
| scripts/ | Maintenance and API verification scripts. |
| .data/ | Local persistence for connection configurations (JSON-based). |
Licensing
By contributing to this project, you agree that your contributions will be licensed under the IDACS Open Source License (IOSL) included in the repository. Always ensure you are not committing code with incompatible licenses.