bcgov / bcgov/lcfs

LCFS - Integrate `@hey-api/client-axios` and `@hey-api/openapi-ts` for Improved Type Checking and API Consistency

Open
#1,155 0 comments 0 reactions 1 assignee Assigned to @kevin-hashimoto View on GitHub
Added Banana 4 Scale Medium Task
Dominant language
Python
Stars
7
Forks
7
Avg merge
2d 7h
Merged PRs (30d)
87

Description

**Describe the task**
Implement `@hey-api/client-axios` and `@hey-api/openapi-ts` to create a client wrapper around Axios for better type checking and synchronization between the frontend and backend. This integration will generate TypeScript types and RPC methods from the OpenAPI specification, ensuring that the frontend has accurate type definitions that reflect the current state of the API. Additionally, set up a file watcher to regenerate the schema on the frontend whenever the backend schema updates, and update existing frontend hooks to use the new structured types.

**Purpose**
This task will enhance type safety and consistency between the frontend and backend, reducing runtime errors and improving the developer experience. Keeping the frontend synchronized with the backend schema changes will facilitate seamless integration and minimize type-related discrepancies.

**Acceptance Criteria**
- [ ] Install `@hey-api/client-axios` and `@hey-api/openapi-ts` in the frontend project.
- [ ] Implement the client wrapper around Axios using `@hey-api/client-axios`.
- [ ] Configure `@hey-api/openapi-ts` to generate TypeScript types and RPC methods from the backend OpenAPI spec.
- [ ] Set up a file watcher to regenerate the frontend schema whenever the backend updates its OpenAPI specification.
- [ ] Refactor all existing frontend hooks to use the new API-structured types.
- [ ] Ensure that the type generation and client wrapper integration are documented for future reference.
- [ ] Verify that the updated types and hooks pass all existing frontend tests and functionality checks.

**Development Requirements**
1. **Install Packages**:
- Install `@hey-api/client-axios` and `@hey-api/openapi-ts` in the frontend project using npm or yarn.

```sh
npm install @hey-api/client-axios @hey-api/openapi-ts
```

2. **Setup Client Wrapper**:
- Configure a new API client wrapper using `@hey-api/client-axios` to replace or augment existing Axios client setups.

3. **Generate Types from OpenAPI**:
- Configure `@hey-api/openapi-ts` to generate TypeScript types and RPC methods from the backend OpenAPI spec.
- Ensure the configuration points to the correct OpenAPI spec URL or file.

```sh
hey-api openapi-ts generate --input --output
```

4. **Implement File Watcher**:
- Set up a file watcher to automatically regenerate the TypeScript schema whenever the backend OpenAPI spec changes.
- Use tools like `nodemon` or custom scripts in combination with the type generation command.

```sh
nodemon --watch --exec "hey-api openapi-ts generate --input --output "
```

5. **Update Frontend Hooks**:
- Refactor all existing custom hooks and API calls in the frontend to use the new structured types and methods provided by the generated TypeScript types.
- Ensure that all hooks properly utilize type definitions for improved type safety and consistency.

6. **Testing and Verification**:
- Run frontend tests to ensure all functionality is intact.
- Verify that type errors are reduced and that the frontend accurately reflects the structure of the backend API.
- Manually test critical paths in the application to confirm type consistency and correctness.

**Additional Context**
- This task will require coordination with backend developers to ensure the OpenAPI spec is kept updated and accessible.
- Document the process for regenerating the schema and updating hooks, providing a guide for developers on how to maintain synchronization between the frontend and backend.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.