Customizing and Deploying the Thrinacia Fabric Next.js Frontend

Thrinacia Fabric includes a modern Next.js frontend that can be customized independently from the Fabric backend. Customers with frontend source access can develop changes locally, maintain them in a
private Git repository, and deploy approved versions to staging or production.

This guide covers the complete workflow, from cloning the repository through verifying a live deployment.

Before You Begin

Your Thrinacia customer panel provides the following information for each Fabric instance:

Instance and login URLs
Frontend Git repository URL
Gitea username and password
SSH hostname and port
SSH username and password
Frontend Git working directory

Each staging or production instance has its own frontend repository and deployed working directory. Confirm that you are using the correct instance before pushing or deploying changes.

Recommended: Develop and verify changes on a staging instance before applying them to production.

1. Install the Development Requirements

The Fabric frontend requires Git, Node.js, and pnpm. Use the Node.js version specified by the repository if an .nvmrc file or a package.json engine requirement is present.

Confirm that Git and Node.js are installed:

git --version

node --version

Enable pnpm through Corepack:

corepack enable

corepack prepare pnpm@latest --activate

pnpm --version

If the repository specifies a particular pnpm version, use that version instead of automatically selecting the latest release.

2. Clone the Frontend Repository

Copy the frontend repository URL from the applicable instance in your Thrinacia customer panel.

git clone GIT_REPOSITORY_URL

cd FRONTEND_REPOSITORY_DIRECTORY

Enter your assigned Gitea username and password when prompted.

Verify the repository and current branch:

git remote -v

git branch --show-current

git status

The repository normally uses the main branch unless your project follows a separate branch workflow.

3. Install the Project Dependencies

Install the exact dependency versions recorded in the repository lockfile:

pnpm install --frozen-lockfile

The --frozen-lockfile option prevents dependency versions from changing unexpectedly. If you intentionally modify project dependencies, use pnpm install and commit the resulting
changes to both package.json and pnpm-lock.yaml.

4. Configure the Local Environment

If the repository contains an example environment file, create a local configuration from it:

cp .env.example .env.local

Configure the public API base URL for the Fabric instance you want to use:

NEXT_PUBLIC_API_BASE_URL=https://YOUR-FABRIC-INSTANCE.example.com

Use a staging API while developing changes intended for staging. Avoid connecting experimental frontend code to production unless it is specifically required.

Security notice: Never commit passwords, private API keys, payment credentials, or production secrets. Files such as .env and .env.local should remain excluded
through .gitignore.

5. Run the Frontend Locally

Start the Next.js development server:

pnpm dev

The terminal will display the local address. It commonly uses:

http://localhost:3000

Next.js automatically reloads most frontend changes while the development server is running.

What Can Be Customized?

Depending on your project requirements, frontend customizations may include:

Public navigation and page layouts
Campaign, fundraising, and investment interfaces
Commerce and product storefronts
Creator, contributor, buyer, and vendor dashboards
Administrative interfaces
Branding, colors, typography, and imagery
Translation strings and localized presentation
Custom workflows powered by the Fabric API

The frontend should continue using the Fabric API for campaigns, products, users, payments, permissions, and platform data. Avoid duplicating backend business rules inside the browser.

6. Test Your Changes

Review the application on desktop, tablet, and mobile screen sizes. Test any workflow affected by your changes, including:

Navigation and responsive menus
Registration, sign-in, and account recovery
Campaign browsing and campaign details
Campaign creation and editing
Products, carts, orders, and checkout
User account and administrative screens
Images, uploads, and downloadable files
Localization and language switching
Loading, empty, error, and permission-denied states

Use the browser developer tools to check for JavaScript errors, failed API requests, missing images, and other asset-loading problems.

7. Validate a Production Build

A working development server does not guarantee that the optimized production build will succeed. Always run a production build before committing:

pnpm build --webpack

If the repository provides linting, type-checking, or testing commands, run them as well:

pnpm lint

pnpm typecheck

pnpm test

The available commands are listed in the scripts section of package.json. Do not deploy a frontend that fails its production build.

8. Commit and Push the Changes

Review exactly what will be committed:

git status

git diff

Stage and commit the approved files:

git add .

git commit -m "describe the frontend changes"

git push origin main

The private repository now contains the frontend version that can be deployed to the corresponding Fabric instance.

9. Connect to the Instance Through SSH

Use the SSH hostname, port, username, and password displayed in your customer panel:

ssh -p SSH_PORT SSH_USERNAME@SSH_HOSTNAME

SSH may display a host-key confirmation the first time you connect. Confirm it only after verifying that the hostname and port match the values supplied by Thrinacia.

10. Open the Deployed Frontend Directory

After connecting, open the frontend Git directory shown in the customer panel:

cd FRONTEND_GIT_DIRECTORY

Confirm the branch and working-tree state:

git branch --show-current

git status

git remote -v

If the server contains uncommitted changes, stop before pulling. Review those changes so they are not overwritten or mixed with the deployment.

11. Pull and Build the New Version

Pull the committed changes using a fast-forward-only update:

git pull --ff-only origin main

If project dependencies changed, install them from the lockfile:

pnpm install --frozen-lockfile

Remove the previous generated build and create a fresh production build:

rm -rf .next

pnpm build --webpack

The running website is not replaced until the frontend service is restarted.

12. Activate the Deployment

Use the restart procedure assigned to your Fabric instance:

FRONTEND_RESTART_COMMAND

Some managed instances restrict service restarts to Thrinacia operations. In that case, complete the Git pull and production build, then request deployment activation through Thrinacia support.

Do not guess the service name or use broad process-termination commands. Use only the restart procedure assigned to your instance.

13. Verify the Deployment

Open the staging or production URL and confirm that:

The website loads successfully over HTTPS
The expected frontend changes are visible
API requests complete successfully
Authentication and protected pages work
Images, fonts, and other assets load correctly
Desktop and mobile layouts remain usable
No critical browser-console errors are present

A hard refresh or private browser window can help distinguish a deployment problem from stale browser assets.

Recommended Staging-to-Production Workflow

Make the frontend changes locally.
Run and test the local development server.
Complete a local production build.
Commit and push to the staging frontend repository.
Deploy and verify the staging instance.
Obtain approval for the tested version.
Apply the approved changes to the production repository.
Deploy and verify the production instance.

Rolling Back a Frontend Deployment

If a deployed version causes a problem, review the recent commit history:

git log --oneline --decorate -10

Create a new commit that reverses the problematic change:

git revert COMMIT_ID

git push origin main

Pull, rebuild, and restart the frontend using the normal deployment process.

Using git revert is preferable to rewriting shared branch history because it preserves a clear record of the rollback.

Important Practices

Use staging before production.
Keep credentials and environment files out of Git.
Commit intentional source changes before deployment.
Never edit generated .next files manually.
Do not force-push a deployed production branch.
Do not make untracked production-only source changes.
Run a production build before every deployment.
Keep each instance’s repository and SSH credentials separate.

Managed Update Behavior

When a customer receives write access to a Fabric frontend repository, automatic frontend source updates may be disabled for that instance. This protects customer customizations from being overwritten by
centrally deployed frontend updates.

Customers can review and apply compatible upstream improvements through an agreed update process. Backend updates remain managed separately unless a customer agreement explicitly includes backend source
access and maintenance responsibilities.

Need Assistance?

If you encounter build errors, API compatibility issues, deployment problems, or questions about upstream Fabric updates, contact Thrinacia support with the instance identifier, repository name, commit ID,
and relevant build output.