Tax API and Forms
Tax API and Forms
Welcome to the first unit of the new course, Tax Management and Full App Polish. In the previous course, you completed the first practical version of the admin product workspace. The app could already create, edit, archive, sort, and synchronize products, which meant the internal tooling had moved beyond simple data display and into real operational workflows. That was a major step because it established the same pattern you have used throughout the project: semantic API helpers, refresh-based UI state, small reusable components, and pages that stay focused on workflow instead of low-level request plumbing.
This new course shifts that same mindset toward tax management. In this lesson, you will start by building a small tax API module in src/lib/api/tax.ts, then create a reusable tax form in src/components/admin/TaxRateForm.tsx. The big idea is very similar to the product form lesson: keep the request layer compact and semantic, keep the form controlled and reusable, and make sure the component boundary stays clean so the page that uses the form can stay focused on higher-level workflow later.
Previously
Previously, the admin workspace became much more synchronized and trustworthy. src/components/admin/ProductAdminPageClient.tsx derived a sorted product list with useMemo, kept the selected product aligned with refreshed collection data through an effect, reset the create form by remounting it after successful creation, and added archive actions to the list. That work reinforced an important principle: internal tools feel reliable when they reflect canonical server state clearly and quickly.
This tax unit builds on the same frontend habits, but with a smaller surface area. Instead of a large two-column product workspace, you are starting with a tight tax API module and a compact tax-rate form. The lesson is intentionally focused: first define the named request helpers, then build a controlled form that can submit a tax rate cleanly and repeatedly.
Keeping the Tax API Module Small and Semantic
The file src/lib/api/tax.ts is intentionally compact. That is a very good design choice. API helper modules are easiest to use when they expose a small set of clear verbs that match the domain, rather than trying to contain state, UI logic, or transport setup scattered across components.
Here is the full tax API file:
-
The module imports
apiRequestandtoRequestInitfromsrc/lib/api/client.ts, which keeps it aligned with the shared request pattern used elsewhere in the app. That is important because page components should not have to remember how to set headers, stringify bodies, or buildRequestInitobjects themselves when the shared client already solves that problem. -
listTaxRates()returnsapiRequest<TaxRate[]>('/api/tax/rates'), which makes the collection read very explicit. TheTaxRate[]generic matters because it tells TypeScript and the rest of the UI that this helper resolves to an array of tax-rate records rather than a single object. -
getTaxRate(countryCode)rounds out the read surface even though the immediate form work does not rely on it yet. This is a good example of a helper that belongs in the module because it completes the tax read vocabulary and keeps future page code consistent with the rest of the API layer. -
upsertTaxRate(countryCode, input)usestoRequestInit('PUT', input), which is exactly the right pattern for mutation helpers in this project. The helper stays easy to read because it expresses intent — “upsert this tax rate” — while delegating transport details to the shared API client utilities. -
deleteTaxRate(countryCode)follows the same compact style withtoRequestInit('DELETE'). The function stays as direct and focused as the others, which keeps the whole module symmetrical and easy to scan. -
Just as importantly, notice what this file does not contain: no
useState, nouseEffect, no toasts, no UI conditions, and no local caching. This is purely a named request-helper module, and that narrow responsibility is one of its biggest strengths.
A page or component that later calls upsertTaxRate(...) or deleteTaxRate(...) will read much more clearly because the UI can stay focused on workflow instead of building URLs and request options inline.
