Plugin: Feedback
Relevant source files
The following files were used as context for generating this wiki page:The @better-auth-kit/feedback plugin provides a straightforward way for users to submit feedback about an application. It is a part of the Better Auth Kit, designed to be a modular and configurable addition to any project using better-auth. The plugin handles feedback submission through a dedicated API endpoint, validates the input, and stores it in the database.
It offers various configuration options, such as setting length constraints for feedback, limiting submissions per user, and controlling access based on authentication status or custom logic. It also includes a client-side helper for easy integration with front-end applications.
Sources: packages/plugins/feedback/README.md, packages/plugins/feedback/src/index.ts, packages/plugins/feedback/package.json
Core Components
Plugin Initialization
The feedback plugin is initialized by calling the feedback() function and passing it to the betterAuth configuration. The function accepts an optional FeedbackOptions object to customize its behavior.
Sources: packages/plugins/feedback/src/index.ts:28-48
Configuration (FeedbackOptions)
The plugin's behavior can be customized through the FeedbackOptions object.
| Option | Type | Default | Description - |
| minLength | number | 10 | Minimum length of the feedback text. - |
| maxLength | number | 500 | Maximum length of the feedback text. - |
| feedbackLimit | number | undefined | Limits the number of feedback submissions a single user can make. No limit if undefined. - |
| canSubmitFeedback | (user: User) => boolean \| Promise<boolean> | undefined | A function to determine if a specific user is allowed to submit feedback. All authenticated users are allowed if undefined. - |
| requireAuth | boolean | true | If true, only authenticated users can submit feedback. If false, anonymous feedback is allowed. - |
| schema | object | undefined | Allows overriding the default database schema configuration for the feedback table. - |
| additionalFields | Record<string, FieldAttribute> | {} | Defines extra fields to be added to the feedback database table. - |
| onFeedback | (params: { feedback: FeedbackEntry; user: User \| null; }) => void \| Promise<void> | undefined | A server-side callback function that executes after a feedback entry is successfully created. - |
Sources: packages/plugins/feedback/src/types.ts:5-48, packages/plugins/feedback/src/index.ts:29-37
Database Schema
The plugin defines a feedback table in the database to store all submissions.
Sources: packages/plugins/feedback/src/schema.ts:3-14
This diagram shows the entity relationship for the feedback table.
Default Schema
The base schema for a feedback entry is defined as follows:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier for the feedback entry. |
text | string | Yes | The content of the feedback. |
userId | string | Yes | The ID of the user who submitted the feedback. |
createdAt | datetime | Yes | The date and time the feedback was submitted. |
Sources: packages/plugins/feedback/src/schema.ts:5-12
Schema Modifications
requireAuth: false: If authentication is not required, theuserIdfield in thefeedbacktable is marked as optional.additionalFields: This option allows developers to add custom columns to thefeedbacktable. The plugin will automatically handle these fields during submission.schema: This option allows for deeper customization, such as changing the model name.
Sources: packages/plugins/feedback/src/index.ts:44-47, packages/plugins/feedback/src/index.ts:54-58
API Endpoint: POST /feedback/submit
The plugin exposes a single API endpoint to handle the submission of new feedback.
Sources: packages/plugins/feedback/src/index.ts:65-179
Request
- Method:
POST - Middleware:
sessionMiddlewareis used to check for an active user session. - Body: The request body is a JSON object. It must contain a
textfield and can include anyadditionalFieldsdefined in the plugin configuration. The body is validated usingzod.
Sources: packages/plugins/feedback/src/index.ts:67-77
Server-Side Logic Flow
The following diagram illustrates the logic executed on the server when a request is received at the /feedback/submit endpoint.
Error Codes
The endpoint can return specific error codes upon failure.
| Code | Message |
|---|---|
FEEDBACK_TOO_SHORT | Feedback text is too short |
FEEDBACK_TOO_LONG | Feedback text is too long |
USER_NOT_LOGGED_IN | User must be logged in to submit feedback |
USER_NOT_FOUND | User not found |
FEEDBACK_LIMIT_REACHED | You have reached your feedback submission limit |
USER_NOT_ALLOWED | You are not allowed to submit feedback |
Sources: packages/plugins/feedback/src/index.ts:12-20
Client-Side Integration
The plugin provides a client-side helper, feedbackClient, to simplify interactions with the API from a front-end application.
feedbackClient()
This function, when passed to the client-side betterAuth instance, adds a feedback object to the client.
Sources: packages/plugins/feedback/src/client.ts:3-11
client.feedback.submit()
This method sends a POST request to the /feedback/submit endpoint. It takes an object containing the text and any other required fields.
Example from tests:
// packages/plugins/feedback/tests/feedback.test.ts:18-24
const response = await client.feedback.submit({
text: "This is a valid feedback with proper length",
fetchOptions: {
headers,
},
});
Sources: packages/plugins/feedback/tests/feedback.test.ts:18-24
End-to-End Sequence Diagram
This diagram shows the full sequence of a user submitting feedback from the client to the database.
Summary
The Feedback plugin is a powerful yet simple tool for collecting user feedback. Its high degree of configurability allows developers to tailor it to specific application needs, from simple anonymous suggestion boxes to more complex, permission-based feedback systems. By providing both server-side logic and a client-side helper, it offers a complete, end-to-end solution for feedback management within the Better Auth ecosystem.