<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Aniq UI]]></title><description><![CDATA[Practical notes on Next.js, Tailwind CSS and Arabic right-to-left layouts from the team behind Aniq UI: Next.js templates with dashboards, APIs and full RTL sup]]></description><link>https://aniqui.hashnode.dev</link><image><url>https://cdn.hashnode.com/uploads/logos/6af481aaf949cdb2e44c464e/2b67a9dd-ba92-417e-99ec-189482b0ff44.png</url><title>Aniq UI</title><link>https://aniqui.hashnode.dev</link></image><generator>RSS for Node</generator><lastBuildDate>Wed, 18 Nov 2026 13:42:04 GMT</lastBuildDate><atom:link href="https://aniqui.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[How to Build a SaaS Admin Panel With an AI Assistant in Next.js]]></title><description><![CDATA[Build an admin panel with an AI assistant in Next.js: roles, projects, users, Arabic and RTL, Docker and going live, with a worked example.]]></description><link>https://aniqui.hashnode.dev/build-saas-admin-panel-ai-assistant-nextjs</link><guid isPermaLink="true">https://aniqui.hashnode.dev/build-saas-admin-panel-ai-assistant-nextjs</guid><category><![CDATA[Next.js]]></category><category><![CDATA[Artificial Intelligence]]></category><category><![CDATA[SaaS]]></category><category><![CDATA[Web Development]]></category><dc:creator><![CDATA[Aniq UI]]></dc:creator><pubDate>Mon, 16 Nov 2026 21:13:34 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af481aaf949cdb2e44c464e/169dba6f-acd4-4b83-aa6b-d477e86d8f03.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p><em>Originally published on the <a href="https://www.aniq-ui.com/en/blog/build-saas-admin-panel-ai-assistant-nextjs">Aniq UI blog</a>.</em></p>
<p>By the end of this guide you will have an internal admin panel with an AI assistant running on your computer and ready for a server. It is a Next.js dashboard with its own API behind it, and you build it from the Aniq UI Admin Dashboard Template 2 instead of starting from an empty folder.</p>
<p>The steps work for a SaaS admin panel, a back office for a small company, or any internal tool where a team needs lists, roles and a way to ask questions about their own data. To keep it concrete, we walk one made-up company through the whole job, from the first download to a live address, and we stop at every point where something usually goes wrong.</p>
<blockquote>
<p><strong>About this example</strong></p>
</blockquote>
<blockquote>
<p>Larkspur Software is an illustrative business we use to show the steps. It is not a client story, and the numbers in it are examples, not results.</p>
</blockquote>
<h2>Before you start: decisions to make</h2>
<p>Most of the pain in an internal tool comes from choices made late. Settle these six before you open a terminal, and the rest of the guide goes faster.</p>
<ul>
<li><p><strong>Who signs in, and what may each person do?</strong> Write the list of roles on paper first. The template ships five (Super Admin, Admin, Manager, Editor, Viewer) and you can reshape them, but it is easier to reshape with a plan.</p>
</li>
<li><p><strong>What are your records?</strong> The template comes with users, projects, tasks and app settings. If your business revolves around something else, such as orders or tickets, decide now whether you will rename what exists or add a new module to the API.</p>
</li>
<li><p><strong>Which languages?</strong> English and Arabic ship. A third language is possible but is more work, so know before you start whether you need it.</p>
</li>
<li><p><strong>Who pays for AI?</strong> Either the company holds one provider key on the server, or each person brings their own. The choice changes your bill and your privacy story, and step 8 covers both.</p>
</li>
<li><p><strong>Where will it run?</strong> A single small server using Docker, or Vercel for the dashboard with the API on a Docker host. Pick the shape early so you set the right addresses once.</p>
</li>
<li><p><strong>Which database?</strong> SQLite is the default and needs no setup. MySQL is a configuration change. A host without a persistent disk is the usual reason to pick MySQL.</p>
</li>
</ul>
<h2>The brief</h2>
<p>Larkspur Software is a small agency that builds web apps for other companies. The office needs one place to run its work. Here is what the team asks for:</p>
<ul>
<li><p>A sign-in for staff, with different levels of access: the owner sees everything, developers edit projects, contractors only read.</p>
</li>
<li><p>A list of every client project, with its status, its environment (staging or production) and its current version.</p>
</li>
<li><p>A list of client accounts, with a quick way to find the ones who never verified their email.</p>
</li>
<li><p>An assistant that answers plain questions such as "which projects are blocked?" and shows the answer as a table or a chart.</p>
</li>
<li><p>English and Arabic, because two client teams read Arabic.</p>
</li>
<li><p>A first run on a laptop, then a small server on the agency's own domain.</p>
</li>
<li><p>Control over who can use the assistant, since it can change records and the AI provider bills for usage.</p>
</li>
</ul>
<h2>How the template covers the brief</h2>
<table>
<thead>
<tr>
<th>Need</th>
<th>Where it lives</th>
<th>What you use</th>
</tr>
</thead>
<tbody><tr>
<td>Staff with different access</td>
<td>Dashboard and API</td>
<td>Admin Management and Admin Roles screens; permissions named like projects.edit</td>
</tr>
<tr>
<td>Client project tracking</td>
<td>Dashboard and API</td>
<td>Projects screen with status, environment, version and an English and Arabic name</td>
</tr>
<tr>
<td>Client accounts</td>
<td>Dashboard and API</td>
<td>Users and Deleted users screens, filters, verify and restore actions</td>
</tr>
<tr>
<td>Plain-language questions</td>
<td>Dashboard and API</td>
<td>AI Assistant screen, with a provider key from you</td>
</tr>
<tr>
<td>English and Arabic</td>
<td>Dashboard</td>
<td>/en and /ar addresses, message files under messages/</td>
</tr>
<tr>
<td>Laptop, then a server</td>
<td>Docker and configuration</td>
<td>Docker Compose, .env files, a web server in front</td>
</tr>
<tr>
<td>Control over the assistant</td>
<td>API</td>
<td>The ai_chat.use permission on a role</td>
</tr>
</tbody></table>
<p><code>``````</code> ``</p>
<h2>Template, from scratch or a hosted builder</h2>
<p>There are three honest ways to get an admin panel with an AI assistant, and each fits a different team.</p>
<p><strong>From scratch.</strong> You get exactly the structure you want and nothing extra. You also build sign-in, roles with live updates, filtered lists, a chat interface that renders tables and charts, and the API behind all of it. This suits teams with an unusual product and plenty of engineering time. For everyone else it means a long stretch spent on screens that every admin panel needs.</p>
<p><strong>A hosted builder.</strong> A low-code or internal-tool service gets you a working screen quickly and handles hosting for you. In exchange you work inside its component set and its pricing model, and moving away later usually means rebuilding. Check what it charges per user, what you can export, and whether it supports right-to-left layouts before you commit.</p>
<p><strong>A template with source code.</strong> You start with finished screens, a working API and an assistant, and you own the code. You pay once for the template, host it yourself, and change anything you like. The cost is that you must be comfortable with Next.js, and later with NestJS if you extend the API. The license does not let you publish or resell the source, but it does cover unlimited projects, including ones for clients.</p>
<p>Larkspur has developers on staff and wants to keep client data on its own server, so it takes the template route. If nobody on your team writes code, a hosted builder is the more realistic choice.</p>
<h2>An example launch plan by week</h2>
<p>This is a sample schedule for Larkspur, not a benchmark. Your own pace will differ.</p>
<ul>
<li><p><strong>Week 1, get it running.</strong> Download the ZIP, start it with Docker, click through every screen, and try both sample accounts. Decide the six questions above.</p>
</li>
<li><p><strong>Week 2, make it theirs.</strong> Brand it, rebuild the roles, create the real staff accounts, and delete the sample admins.</p>
</li>
<li><p><strong>Week 3, load the work.</strong> Enter real projects and client accounts, add provider keys, and let two or three people use the assistant with real questions.</p>
</li>
<li><p><strong>Week 4, harden and ship.</strong> Set production environment values, deploy to the server, check the health address, and walk through the launch checklist near the end of this post.</p>
</li>
</ul>
<h2>Step by step</h2>
<h3>1. Choose the package</h3>
<p>The template comes in three packages. The Full Stack package holds the dashboard and the NestJS API. The Admin Dashboard package is the dashboard alone, running against a small mock server built into it, with the sample records stored in your browser. The Backend API package is the API alone.</p>
<p>Larkspur wants real data and a real assistant, so it takes Full Stack. If you only want to design screens first, the Admin Dashboard package is enough, and you can point it at an API later. If you already have a front end and only need the server, the Backend API package gives you the routes, the roles logic and the assistant's tools.</p>
<p><strong>Check:</strong> after the download, your account should show a ZIP named for the package you bought. <strong>Usually goes wrong:</strong> buying the dashboard package and expecting an API in it. The dashboard alone cannot store anything outside the browser.</p>
<h3>2. Run it locally with Docker</h3>
<p>Install Docker Desktop (or Docker Engine on Linux) and nothing else. Then work through these sub-steps.</p>
<p><strong>2a. Download.</strong> Open My templates in your Aniq UI account and download the Full Stack ZIP.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/d3a06f8e-56a5-4624-b990-62d911f18626.webp" alt="Documentation video still of downloading the Full Stack ZIP of the Admin Dashboard Template 2" /></p>
<p>Look at which package is chosen on the download page, because the folder names in the later steps depend on it.</p>
<p><strong>2b. Unzip and open the folder.</strong> Unpack the archive and start a terminal inside the <code>dashboard-2-full-stack</code> folder (on Windows, unpack it with File Explorer first).</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/78244389-29e4-4e8e-a990-26b5ff074304.webp" alt="Documentation video still of unzipping the Full Stack package and opening its folder in a terminal" /></p>
<p>Look at the folder contents: you should see <code>back-end</code>, <code>front-end</code> and <code>docker-compose.yml</code> side by side.</p>
<p><strong>2c. Start both apps.</strong></p>
<pre><code class="language-bash">docker compose up --build
</code></pre>
<p>On the first start Docker builds two images and seeds the database, so give it a few minutes. Later starts take seconds.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/705672d6-9d8a-4625-badc-40dbe3740dec.webp" alt="Documentation video still of starting the dashboard and API together with Docker Compose" /></p>
<p>Look at the terminal: it prints build progress first, and the dashboard waits until the API reports itself healthy.</p>
<p><strong>2d. Open it.</strong> Go to <code>localhost:3030</code> and use the account <code>admin@example.com</code> with the password <code>Admin@123</code>. Arabic lives at <code>/ar</code>. The API answers at <code>localhost:8000/api/health</code> once its database is ready.</p>
<p><strong>What to check:</strong> the health address should answer, and the dashboard should list data on its first screen. <strong>What usually goes wrong:</strong> a port is already in use. If another program holds 3030 or 8000, create a file named <code>.env</code> next to <code>docker-compose.yml</code> and set <code>DASHBOARD_PORT=3040</code> (or <code>API_PORT</code> for the API), then run the same command again. A start that seems stuck is normally still seeding sample data.</p>
<p>To stop the apps, press Ctrl+C. Your data stays in a Docker volume. Be careful with <code>docker compose down -v</code>: the <code>-v</code> deletes the volume, and the next start brings back fresh sample data.</p>
<h3>3. Know the other ways to run it</h3>
<p>You will not use all of these, but each solves a real situation.</p>
<p><strong>The dashboard alone.</strong> With the Admin Dashboard package, you build one image and start one container. With no API address set, it runs on its mock server and needs no back end.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/a13bed16-1596-4c24-957a-52fea4cc7f25.webp" alt="Documentation video still of unzipping the Admin Dashboard package and opening its folder" /></p>
<p>Look at the folder name in the terminal: this package extracts to a different folder than the Full Stack one.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/176dc588-de88-4273-a96f-d7895e107252.webp" alt="Documentation video still of building the Admin Dashboard Docker image" /></p>
<p>Look at the build output: the dependencies and the build both happen inside the image, so the first build needs an internet connection.</p>
<p><strong>The API alone.</strong> With the Backend API package, you build an image and run it with a volume that holds the database file. The first run seeds that database with the sample records and accounts. Every route sits under <code>/api</code>, and you check it with the health address.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/4a472b7b-f1fb-4d80-8a90-eb920c2e84e4.webp" alt="Documentation video still of unzipping the Backend API package and opening its folder" /></p>
<p>Look at the files in the folder, which include a <code>Dockerfile</code>, <code>package.json</code> and <code>.env.example</code>.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/4e31e195-ccd1-4d8a-850f-451f411accc2.webp" alt="Documentation video still of building the Backend API Docker image" /></p>
<p>Look at the image being built: the API image is separate from the dashboard's.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/f18ee92e-2698-4ef1-b82d-115cb2ff8a72.webp" alt="Documentation video still of starting the Backend API container and checking its health" /></p>
<p>Look at the health check at the end: a working API answers with an <code>ok</code> status.</p>
<p><strong>Without Docker.</strong> Install Node.js 22.9 or newer and run <code>corepack enable</code> once. Start the API first, because the dashboard reads all its data from it. In <code>back-end</code>, copy the example settings, create the database with <code>yarn seed</code>, then run <code>yarn dev</code>. In <code>front-end</code>, copy the example settings and start it the same way.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/d112933e-89da-4bdd-b639-c9cd1708c8ef.webp" alt="Documentation video still of starting the API without Docker using Yarn" /></p>
<p>Look at the first terminal, which runs the API.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/198e6975-f977-4299-abb7-2628bf4d01f9.webp" alt="Documentation video still of starting the dashboard without Docker in a second terminal" /></p>
<p>Look at the second terminal, which runs the dashboard against the API from the first.</p>
<p>The same approach works for the single-app packages.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/5d2a99f9-4071-4019-8a53-527fef8faa6d.webp" alt="Documentation video still of starting the Admin Dashboard package on its sample data without Docker" /></p>
<p>Look at how little is needed here: no <code>.env</code> file means the mock server answers.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/8f1f7872-139a-453b-b197-e4382168f01f.webp" alt="Documentation video still of starting the Backend API package without Docker" /></p>
<p>Look at the API terminal staying open while you use it.</p>
<p><strong>What usually goes wrong:</strong> a Node.js older than 22.9, which makes <code>yarn dev</code> fail on reading <code>.env</code>; a Yarn that answers with version 1.22 because Corepack is off; and a dashboard that shows sample data even though you meant to use your API, because the API address was missing when it was built.</p>
<h3>4. Explore the sample data before you change anything</h3>
<p>The seed loads a small company's worth of records: a dozen admins, five roles carrying 25 permissions, 15 users, 15 projects, 10 tasks and 13 app settings, plus some deleted users and projects to practise restoring. Click through the sidebar from top to bottom, ending on the page that lists every UI component.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/dce8a0ae-5bfe-4747-8e90-83b4b5b74642.webp" alt="Documentation video still of browsing the Admin Dashboard Template 2 during a tour" /></p>
<p>Look at how the sidebar groups the screens, since you will rename and prune this menu later.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/462918ae-bcdc-4d9a-9561-9d5dd150b6ba.jpg" alt="Overview screen of the Admin Dashboard Template 2 with key figures, charts and quick tasks" /></p>
<p>Look at the top of the overview: key figures, charts, a calendar and quick tasks share one screen, and the widgets can be rearranged.</p>
<p>Then sign out and sign in as <code>john.smith@admin.com</code> with the password <code>admin123</code>. This account has the Viewer role. It can read every list but cannot create, edit or delete anything, and it cannot open the assistant. Seeing that difference early tells you how the permission system behaves, which matters for step 6.</p>
<p><strong>What to check:</strong> you can explain, in one sentence each, what Super Admin and Viewer can do. <strong>What usually goes wrong:</strong> people edit sample records first and then forget which data is real. Keep the sample data untouched until you are ready to replace it in bulk.</p>
<h3>5. Put the agency's name on it</h3>
<p>All branding sits in the dashboard folder (<code>front-end</code> in the Full Stack package). Run <code>yarn dev</code> there while you edit and the page reloads on every save. Four places matter most:</p>
<ul>
<li><p><code>src/config/brand.config.ts</code> holds <code>BRAND_CONFIG</code>: the name, the company, the page metadata and the installed-app details, in English and Arabic.</p>
</li>
<li><p><code>public/assets/images/logo-for-lightmode.png</code> and <code>logo-for-darkmode.png</code> are the two logos. Replace the files and keep the names.</p>
</li>
<li><p><code>src/styles/theme-variables.css</code> defines every colour once for light and once for dark. The brand colour is <code>--primaryColor</code>.</p>
</li>
<li><p><code>messages/&lt;namespace&gt;/en.json</code> and <code>ar.json</code> hold every word on screen. Edit both languages together.</p>
</li>
</ul>
<p>Larkspur changes the name, swaps both logos and picks one new primary colour. That is enough for the dashboard to feel like theirs. Components read colours through variables such as <code>bg-[var(--surface)]</code>, so any component you add later keeps both themes if it does the same.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/b5e5fc0a-37b0-4e29-9647-4c4ed0a113df.jpg" alt="UI component library page of the Admin Dashboard Template 2 with buttons, tables, dialogs and charts" /></p>
<p>Look at the component page: it is the quickest way to see your new colour on every kind of control at once.</p>
<p><strong>What to check:</strong> switch between light and dark in the header, then open the component page in both. <strong>What usually goes wrong:</strong> a logo with a baked-in background colour that looks wrong in one theme. Export both logos with transparent backgrounds.</p>
<h3>6. Set up staff and roles</h3>
<p>The seed ships five roles: Super Admin, Admin, Manager, Editor and Viewer. One person can carry more than one role, and they receive the combined permissions of all of them. Permissions are named <code>module.action</code>, for example <code>users.view</code>, <code>projects.edit</code> or <code>settings.edit</code>, and there are 25 of them across admins, roles, users, projects, settings and the assistant.</p>
<p>Larkspur maps its team like this: the owner stays Super Admin, the two project leads become Manager, developers become Editor, and contractors become Viewer. Do it in three passes:</p>
<ol>
<li><p>Open Admin Roles and read what each role grants. Rename or trim until the roles match the paper plan.</p>
</li>
<li><p>Open Admin Management and create each real person, then assign their roles.</p>
</li>
<li><p>Sign in as one person per role and try the actions that role should and should not have.</p>
</li>
</ol>
<p>If you change a role while someone is signed in, their menus and buttons update without a reload, because the API tells their dashboard over a WebSocket.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/87b498ae-80fb-448e-89b2-e937182ad0ea.jpg" alt="Admin management screen of the Admin Dashboard Template 2 listing staff accounts with role chips" /></p>
<p>Look at the role chips on each account: they show at a glance who holds which role.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/16826638-7f9e-4b29-ae1d-f06db23c1ae7.jpg" alt="Roles and permissions screen of the Admin Dashboard Template 2 showing roles and their access policies" /></p>
<p>Look at how permissions are grouped by module, which makes it easy to grant "view" without "edit".</p>
<p>Before anything else, change the passwords of the sample admins under Settings, Security, or delete those accounts. The seed creates them with passwords printed in the public documentation, and the template's guides warn about this more than once for good reason.</p>
<p><strong>What usually goes wrong:</strong> deleting the Super Admin before another admin can manage roles, or giving the Admin role to everyone because it is easier. Start strict and loosen when someone asks.</p>
<h3>7. Load projects and client accounts</h3>
<p>Open Projects and replace the sample rows with Larkspur's real work. A project carries a name and description in English and Arabic, a status (<code>in-progress</code>, <code>ready</code> or <code>blocked</code>), an environment, a version and an optional picture. Deleting is a soft delete: deleted projects move to their own screen and can be restored.</p>
<p>Users work the same way. You can narrow the list by username, email, phone, name or join date, and the top of the page counts verified, unverified and deleted accounts. For Larkspur, that is the screen for client staff who got an invitation and never confirmed it. The resend-verification route answers success but sends no mail, so connect your own mail service before you rely on it.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/635ada72-ca37-4caf-8230-b8e0740f71ba.jpg" alt="User management screen of the Admin Dashboard Template 2 with verified and unverified counts and filters" /></p>
<p>Look at the counts above the table and at the status chips on each row.</p>
<p>If your own product has other records, the API is plain REST under <code>/api</code>, so you can add modules beside the existing ones. Sign in with <code>POST /api/auth/login</code> to get the token every other call needs, and send it as a bearer token. Lists take <code>page</code> and <code>page_count</code>, capped at 100 per page.</p>
<p><strong>What to check:</strong> create a project in English and Arabic, reload, and confirm both names appear when you switch language. <strong>What usually goes wrong:</strong> filling only the English name, which leaves the Arabic list with an empty label.</p>
<h3>8. Turn on the AI assistant</h3>
<p>The assistant is its own screen. You type a question in English or Arabic and the answer is built from the dashboard's data, drawn with the same stat cards, tables, lists, donuts and charts the rest of the panel uses. It can also act: add, change, remove or bring back users, and adjust app settings. It does this only inside the permissions of the person asking.</p>
<p>It runs on Google Gemini, OpenAI or DeepSeek, chosen in a model picker. Conversations are saved per admin in a history sidebar. You have two ways to supply a key:</p>
<ul>
<li><p>Put the provider's key in <code>back-end/.env</code> and restart the API (with Docker Compose, run <code>docker compose up</code> again). Then everyone with access uses your key.</p>
</li>
<li><p>Leave the server without a key. The assistant then asks each person for their own, and it stays in their browser.</p>
</li>
</ul>
<p>Larkspur starts with the second option, so nobody's usage lands on the agency's bill by accident. The docs say Gemini works with free keys, while OpenAI needs billing enabled on the key. A free key can run out of quota, and the assistant says so; pick another model or wait.</p>
<p>Control access with the <code>ai_chat.use</code> permission. Because the assistant can write, give it only to roles you would trust with those writes. Contractors on the Viewer role get none.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/09d5f4d5-7cb7-4f57-9889-aa77cabb3907.jpg" alt="AI assistant screen of the Admin Dashboard Template 2 answering a question with a chart" /></p>
<p>Look at how the reply mixes a written summary with a chart built from the dashboard's own numbers.</p>
<p>Two optional extras exist. A Cloudflare R2 bucket lets people upload profile pictures and image attachments; without it, uploads answer that they are not set up and everything else works. An MCP key you choose switches on the API's MCP endpoint; without one, that endpoint refuses every request.</p>
<p><strong>What to check:</strong> ask three questions you already know the answer to, such as how many projects are blocked, and compare. <strong>What usually goes wrong:</strong> the "asks for an API key" dialog, which only means the server has no key for the model you picked. Paste your own, or add the provider's key to the server file and restart.</p>
<h3>9. Check Arabic and the other language details</h3>
<p>Open <code>/ar</code>. The page sets <code>lang="ar"</code> and <code>dir="rtl"</code> before it draws, so the sidebar moves to the right and tables and menus read right to left. The API also answers in Arabic when a request sends <code>Accept-Language: ar</code>, and projects, settings and countries carry both languages in the database.</p>
<p>Anything you add should use logical Tailwind classes such as <code>ms-2</code>, <code>pe-4</code>, <code>start-0</code> and <code>text-start</code> instead of <code>ml-*</code>, <code>pr-*</code>, <code>left-*</code> or <code>text-left</code>, or the Arabic page comes out wrong. If a third language is ever needed, you add its code in three locale lists, copy each <code>en.json</code> file under the new code, and add it to the language menu. The API keeps answering a new language in English until you add its translations in <code>back-end/src/i18n/</code>.</p>
<p><strong>What to check:</strong> walk every screen you changed in Arabic, including the assistant. <strong>What usually goes wrong:</strong> a text added to <code>en.json</code> only, so the Arabic page shows a missing key.</p>
<h3>10. Go live on a server</h3>
<p>The same <code>docker-compose.yml</code> that ran on the laptop also runs on a server. Give the dashboard and the API each a domain behind Caddy or Nginx, which adds HTTPS, and route the first domain to port 3030 (the dashboard) and the second to port 8000 (the API).</p>
<p>Create <code>.env</code> beside <code>docker-compose.yml</code> and set <code>DASHBOARD_URL</code> and <code>API_URL</code> to the two public addresses. The dashboard bakes the API's address into its built code, and the API takes the same two lines for <code>CORS_ORIGIN</code> and <code>FRONTEND_URL</code>. Put your AI keys and <code>TRUST_PROXY=1</code> in <code>back-end/.env</code>. Then start it in the background:</p>
<pre><code class="language-bash">docker compose up --build -d
</code></pre>
<p>In production the API refuses to start with the example <code>JWT_SECRET</code> or an empty <code>CORS_ORIGIN</code>. With Docker it generates a secret for you and keeps it in the data volume, or you can make your own:</p>
<pre><code class="language-bash">node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
</code></pre>
<p>When it is up, open <code>https://api.your-domain.com/api/health</code> (with your own domain) and look for <code>"status":"ok"</code>. If you prefer, the dashboard alone can go to Vercel from a private Git repository: set <code>ENABLE_EXPERIMENTAL_COREPACK</code> to <code>1</code>, then <code>NEXT_PUBLIC_API_BASE_URL</code>, <code>NEXT_PUBLIC_WEBSOCKET_BASE_URL</code> and <code>NEXT_PUBLIC_BASE_URL</code>. Redeploy after changing any <code>NEXT_PUBLIC_*</code> value, because it is compiled in at build time. Leave <code>NEXT_PUBLIC_DEMO_MODE</code> off unless the site is a public demo.</p>
<p>The default database is SQLite, kept in the <code>/data</code> volume. MySQL is a configuration change: create an empty database, set <code>DB_TYPE</code> and the connection in <code>back-end/.env</code>, and seed it. Pick MySQL if your host has no persistent disk. If you run the API without Docker in production, <code>yarn seed:prod</code> creates the tables once; run it a single time, because a second run resets app settings and the built-in roles' permissions to their sample values.</p>
<p><strong>What to check:</strong> sign in from a different computer, change a role, and watch a second signed-in session update. That proves the WebSocket address is right. <strong>What usually goes wrong:</strong> empty pages with a CORS line in the browser console. The API only answers browsers from the addresses in <code>CORS_ORIGIN</code>, so add the dashboard's real address there and to <code>FRONTEND_URL</code>.</p>
<h2>Running it day to day</h2>
<p>Once Larkspur is live, the work becomes small, repeatable routines.</p>
<ul>
<li><p><strong>Onboarding a person.</strong> Create the admin in Admin Management, assign one role, and send them the address. Do not share the Super Admin account.</p>
</li>
<li><p><strong>Offboarding.</strong> Delete the admin account the same day. Because roles update live, you can also strip a role from someone who is still signed in and their buttons disappear without a reload.</p>
</li>
<li><p><strong>Changing what a role may do.</strong> Edit it on the Admin Roles screen and tell the team. Test with a real account for that role.</p>
</li>
<li><p><strong>Restoring mistakes.</strong> Users and projects are soft deleted. Open the matching Deleted screen to bring one back.</p>
</li>
<li><p><strong>Backups.</strong> With SQLite in Docker, the data lives in one volume. Back that volume up on a schedule that suits how often records change. With MySQL, use your database host's backup tool.</p>
</li>
<li><p><strong>Updating.</strong> After you change code, build the images again, because a running container is a snapshot of the code at build time.</p>
</li>
<li><p><strong>Watching the assistant.</strong> Review who has <code>ai_chat.use</code> now and then.</p>
</li>
</ul>
<h2>What it costs to run</h2>
<p>The template is a one-time purchase from $99, and the package matters: the Full Stack package that this guide uses costs more than the entry price, and the product page lists each one. The licence covers an unlimited number of projects, client work included, as long as you do not share the source code publicly.</p>
<p>Beyond that, you pay for what you add:</p>
<ul>
<li><p>Hosting for the dashboard and the API. A Docker-capable server runs both; Vercel can host the dashboard alone.</p>
</li>
<li><p>AI usage, if you put a provider key on the server. Google, OpenAI and DeepSeek bill by their own pricing pages. If each person brings their own key, the bill is theirs.</p>
</li>
<li><p>A Cloudflare R2 bucket, if you want picture uploads, and a WeatherAPI.com key if you want the weather in the greeting. Both are optional.</p>
</li>
<li><p>A domain name and, if you use it, a mail service for verification emails.</p>
</li>
</ul>
<p>What is free: local development on SQLite, the sample data, the built-in mock API in the dashboard package, and every optional feature you leave switched off.</p>
<h2>What to customise next</h2>
<ul>
<li><p><strong>Roles that match your company.</strong> Rename the five roles and trim their permissions until each one grants only what the job needs.</p>
</li>
<li><p><strong>Your own records.</strong> Add a module to the NestJS API for something Larkspur tracks that is not a project, such as invoices or support tickets, and a screen to match. Each domain in the API has its own module, so a new one slots in beside the others.</p>
</li>
<li><p><strong>New assistant tools.</strong> The assistant routes through an MCP registry that is built to be extended, so you can teach it questions specific to your data.</p>
</li>
<li><p><strong>A third language.</strong> Copy the message files, add the code to the three locale lists, and add the API's translations.</p>
</li>
<li><p><strong>Cleaner production code.</strong> Once your own API is the permanent source of data, the <code>yarn remove:mock</code> script deletes the built-in mock server, and <code>yarn remove:demo</code> removes the public-demo switch. Commit first, since both rewrite files.</p>
</li>
</ul>
<h2>Launch checklist</h2>
<ul>
<li><p>Sample admins deleted or their passwords changed.</p>
</li>
<li><p>Your own <code>JWT_SECRET</code> set, or Docker's generated one confirmed in the data volume.</p>
</li>
<li><p><code>CORS_ORIGIN</code> and <code>FRONTEND_URL</code> hold the dashboard's real address.</p>
</li>
<li><p><code>NEXT_PUBLIC_API_BASE_URL</code> points at the API with <code>/api</code>, and the dashboard was built after you set it.</p>
</li>
<li><p>HTTPS in front of both the dashboard and the API.</p>
</li>
<li><p>The health address answers <code>"status":"ok"</code>.</p>
</li>
<li><p>Every role tested with a real account.</p>
</li>
<li><p><code>ai_chat.use</code> granted only where intended, and provider keys placed where you decided.</p>
</li>
<li><p>Arabic checked on every screen you changed.</p>
</li>
<li><p>Data volume or database backup scheduled.</p>
</li>
<li><p>Demo mode off.</p>
</li>
</ul>
<h2>Common mistakes</h2>
<h3>Going live with the sample admins</h3>
<p>Every seed creates admins with published passwords. Change them or delete them before anyone else can reach the panel, and set your own <code>JWT_SECRET</code>.</p>
<h3>Editing a NEXT_PUBLIC value and expecting a change</h3>
<p>Those values are compiled into the dashboard when it is built. Rebuild (or restart <code>yarn dev</code>) after any edit, and never put a secret in one: anyone can read them in the browser.</p>
<h3>Wiping data with the wrong stop command</h3>
<p><code>docker compose down</code> keeps your data. Adding <code>-v</code> removes the volume, and everything you created goes with it.</p>
<h3>Pages stay empty and the console mentions CORS</h3>
<p>The API only answers browsers from the addresses in <code>CORS_ORIGIN</code>. If the dashboard runs on a new domain or port, add it there and in <code>FRONTEND_URL</code>.</p>
<h3>Handing the assistant to everyone</h3>
<p>The assistant can change users and settings. Grant <code>ai_chat.use</code> to the roles that should have that power and nobody else.</p>
<h3>Passing the example environment file to Docker</h3>
<p>The API image runs in production mode. If you start it with a copy of the example environment file, that file sets development mode over the image's own value. Pass each value you need with <code>-e</code> instead.</p>
<h2>FAQ</h2>
<h3>How do I build an admin panel with an AI assistant in Next.js?</h3>
<p>Start from a dashboard that already has the roles, lists and chat screen, then connect your data and a model provider. In this template, the assistant reads from the same API as the rest of the panel, so you add a key and your records instead of writing chat plumbing.</p>
<h3>Do I need a backend?</h3>
<p>Only for real data. The Admin Dashboard package runs on a mock server inside the browser, which is enough for design work. For a live panel you need an API, and the Full Stack package includes a NestJS one.</p>
<h3>Which AI providers does the assistant support?</h3>
<p>Google Gemini, OpenAI and DeepSeek, picked from a model list. Each person can paste their own key, or you can set one key on the server.</p>
<h3>Does it support Arabic and RTL?</h3>
<p>Yes. Every screen, including the assistant, exists in English and Arabic, and the Arabic pages are laid out right to left.</p>
<h3>Can I use it for clients?</h3>
<p>Yes. The commercial licence covers unlimited projects, including work you build for a client and hand over. You may not publish the source code or resell it as a template.</p>
<h3>Can I change what the assistant is allowed to do?</h3>
<p>You decide who may use it through the <code>ai_chat.use</code> permission, and the assistant acts only within that person's own permissions. Adding new tools is done through its MCP registry in the API.</p>
<h3>Can I try it without installing anything?</h3>
<p>Yes. The live demo runs the same dashboard. For your own machine, the Admin Dashboard package runs on its built-in sample data with no API or AI key at all.</p>
<h3>Can I remove the sample data and the mock server?</h3>
<p>Yes. Two scripts, <code>yarn remove:mock</code> and <code>yarn remove:demo</code>, strip the mock server and the public-demo switch from the code. Commit first, since they rewrite files.</p>
<h2>Try it yourself</h2>
<p>Open the <a href="https://dashboard-2.aniq-ui.com">live demo</a> to click through the dashboard and the assistant. The <a href="https://www.aniq-ui.com/en/templates/next-js-admin-dashboard-template-2">Admin Dashboard Template 2 product page</a> lists the packages, and the <a href="https://www.aniq-ui.com/en/templates/next-js-admin-dashboard-template-2/docs">documentation</a> covers every step above in detail. More options live in the <a href="https://www.aniq-ui.com/en/templates/category/dashboard-nextjs-admin-panel-templates">admin dashboard templates category</a>, and the <a href="https://www.aniq-ui.com/en/blog/admin-dashboard-templates-by-industry">guide to admin dashboard templates by industry</a> helps if your use case differs from this one.</p>
<p>This template is also one of the ten in the <a href="https://www.aniq-ui.com/en/templates/nextjs-templates-bundle">Next.js Templates Bundle</a>, if you expect to build more than one kind of product.</p>
]]></content:encoded></item><item><title><![CDATA[How to Build an Online Store with an Admin Panel in Next.js]]></title><description><![CDATA[Build an online store with a storefront, admin panel and API in Next.js and NestJS, from local setup to Stripe and launch. A worked example.]]></description><link>https://aniqui.hashnode.dev/build-online-store-admin-panel-nextjs</link><guid isPermaLink="true">https://aniqui.hashnode.dev/build-online-store-admin-panel-nextjs</guid><category><![CDATA[Next.js]]></category><category><![CDATA[ecommerce]]></category><category><![CDATA[nestjs]]></category><category><![CDATA[Web Development]]></category><dc:creator><![CDATA[Aniq UI]]></dc:creator><pubDate>Sun, 15 Nov 2026 10:52:37 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6af481aaf949cdb2e44c464e/7dbd2360-3edc-4518-b623-4d5becc948df.jpg" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p><em>Originally published on the <a href="https://www.aniq-ui.com/en/blog/build-online-store-admin-panel-nextjs">Aniq UI blog</a>.</em></p>
<p>By the end of this guide you will know how to build an online store with an admin panel, using Next.js, NestJS and the e-commerce template from Aniq UI. You will have a storefront, an order desk for your team, and an API that holds the catalogue, customers and orders.</p>
<p>We follow one example shop from its first plan to launch day. Each step names the screen or setting involved and uses the exact commands and file paths from the documentation. The same path works for a founder launching a store, or an agency building one for a client.</p>
<blockquote>
<p><strong>About this example</strong></p>
</blockquote>
<blockquote>
<p>Cedar &amp; Cloth is an illustrative business we use to show the steps. It is not a client story, and the numbers in it are examples, not results.</p>
</blockquote>
<h2>The brief</h2>
<p>Cedar &amp; Cloth is a small shop that sells linen shirts and canvas bags. The owner runs it with two people who pack orders. Here is what the shop needs:</p>
<ul>
<li><p>A catalogue of about thirty products, each with sizes and colors, written in English and in Arabic.</p>
</li>
<li><p>Guest checkout, so a first-time visitor can buy without making an account, and track the order afterward.</p>
</li>
<li><p>Payment by card, or cash on delivery for customers who prefer it.</p>
</li>
<li><p>Free shipping above a set order total, and a flat fee below it.</p>
</li>
<li><p>An order desk where the owner has full control and the packers can only view orders.</p>
</li>
<li><p>A home page the owner can rearrange without touching code.</p>
</li>
<li><p>Clean product photos on a plain background, made from phone shots.</p>
</li>
<li><p>A way to see where visitors come from, using Google Analytics.</p>
</li>
</ul>
<h2>How the template covers the brief</h2>
<table>
<thead>
<tr>
<th>Need</th>
<th>Where it lives</th>
<th>What you use</th>
</tr>
</thead>
<tbody><tr>
<td>Bilingual catalogue with variants</td>
<td>Admin dashboard and API</td>
<td>Products and Categories screens, with size and color variants</td>
</tr>
<tr>
<td>Guest checkout and tracking</td>
<td>Storefront</td>
<td>The checkout page and Track Order, which asks for order number and email</td>
</tr>
<tr>
<td>Card or cash on delivery</td>
<td>Storefront and API</td>
<td>Stripe for cards, cash on delivery selected by default</td>
</tr>
<tr>
<td>Shipping rule</td>
<td>Storefront and API</td>
<td>A shipping config file and the orders service, kept in sync</td>
</tr>
<tr>
<td>Order desk and permissions</td>
<td>Admin dashboard</td>
<td>Orders, Admin Management and Admin Roles</td>
</tr>
<tr>
<td>Editable home page</td>
<td>Admin dashboard</td>
<td>The Home Page screen, section by section</td>
</tr>
<tr>
<td>Product photos</td>
<td>Admin dashboard</td>
<td>The product form's AI studio and background removal</td>
</tr>
<tr>
<td>Visitor analytics</td>
<td>Storefront</td>
<td>Tag ids pasted into the storefront's environment file</td>
</tr>
</tbody></table>
<h2>Before you start: decisions to make</h2>
<p>A store touches money, customers and legal duties, so a few decisions are worth making before you write a line of configuration.</p>
<h3>What exactly are you selling?</h3>
<p>Count your products, and for each one decide which options a shopper chooses: size, color, or neither. Variants carry their own SKU, price adjustment and stock, so the shape of your catalogue decides how much data entry you face. Cedar &amp; Cloth sells shirts in several sizes and colors and bags in one size.</p>
<h3>Which languages will you sell in?</h3>
<p>English and Arabic ship ready, including a right-to-left layout. Products and categories hold a name and description in both. A third language is possible for the interface, but it takes edits in several files.</p>
<h3>How will shoppers pay?</h3>
<p>Shoppers can pay by card (Stripe) or choose cash on delivery, and PayPal is not part of the checkout. Stripe charges in US dollars. If you sell in another currency, that is a decision to settle before launch, not after.</p>
<h3>What about shipping and tax?</h3>
<p>The template ships one shipping rule: free from a set order total, a flat fee below it. It applies no tax. If your business must charge tax, plan for that in code or in how you price products.</p>
<h3>Guests, accounts, or both?</h3>
<p>Both work. Guests check out with an email and track orders by number and email. Customers with accounts also get saved addresses, order history and a wishlist.</p>
<h3>Who handles email?</h3>
<p>The template sends none: no confirmations, no shipping notices, no password resets. Choose a mail provider early, because customers expect at least an order confirmation.</p>
<h3>Which AI tools, if any?</h3>
<p>Each one needs its own key, and some need the media bucket. Decide which are worth turning on for launch. A shop that only needs clean product photos can enable background removal and nothing else.</p>
<h2>Step by step</h2>
<h3>Step 1: Choose the package</h3>
<p>The template has four packages: Full Stack (storefront, admin and API), Storefront alone, Admin Dashboard alone, and Backend API alone. The two frontends can each run by themselves on a built-in sample store inside the browser. That is useful for a design pass, but real orders, payments and AI features need the NestJS API.</p>
<p>Cedar &amp; Cloth takes the Full Stack package. The commercial license covers unlimited projects, including stores you build and hand over to a client.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/cb1ebfba-4307-40bf-a65b-7bbd52e0823f.webp" alt="Documentation video still of the Next.js e-commerce template: downloading the ZIP for your package" /></p>
<p>The My templates page lists a ZIP for each package, so choose the one you bought.</p>
<p><strong>What to check:</strong> the Full Stack ZIP extracts to <code>e-commerce-1</code>, containing <code>admin-dashboard</code>, <code>back-end</code>, <code>storefront</code> and <code>docker-compose.yml</code>. Single-app packages extract to their own folder with a <code>Dockerfile</code>, <code>package.json</code> and <code>.env.example</code>.</p>
<h3>Step 2: Run it locally with Docker</h3>
<p>Download the ZIP from My templates, unzip it, and open a terminal in the <code>e-commerce-1</code> folder. Start Docker, then run:</p>
<pre><code class="language-bash">docker compose up --build
</code></pre>
<p>Docker builds three images on the first run and loads a demo store into the database, so expect a few minutes. The storefront opens at <code>localhost:3030</code>, the admin at <code>localhost:3031</code>, and the API at <code>localhost:8000</code>. A busy port can be moved with <code>SITE_PORT</code>, <code>ADMIN_PORT</code> or <code>API_PORT</code> in a <code>.env</code> file next to <code>docker-compose.yml</code>.</p>
<p>Sign in to the admin as the Super Admin (<code>admin@example.com</code>, password <code>Admin@123</code>) and to the storefront as a demo customer (<code>john.doe@example.com</code>, password <code>password123</code>). A read-only staff account, <code>john.smith@admin.com</code> with <code>admin123</code>, shows what the Viewer role sees. Place a test order as the customer, then find it in the admin.</p>
<p>One honest note: on the admin overview, several cards (revenue, sales, goal, visitors, conversion and the map) display placeholder figures until you connect your own numbers. Check which cards are wired to real data before you rely on them.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/7752f520-de64-40cb-8958-68fef7f5fd8e.webp" alt="Documentation video still of the Next.js e-commerce template: unzipping the download and opening the folder" /></p>
<p>This still shows a terminal opened inside the extracted folder, which is where each command should run.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/d63b31fd-44cb-4915-8d20-875c50de769e.webp" alt="Documentation video still of the Next.js e-commerce template: starting the API, the storefront and the admin dashboard with Docker" /></p>
<p>Look for the API passing its health check, since the two frontends start only after it does.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/578a56f4-3d68-4838-b86d-568168eb5101.webp" alt="Documentation video still of the Next.js e-commerce template: starting the API without Docker" /></p>
<p>The Node.js route starts with the API, after the seed has created the database and demo store.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/831f2d59-0ecd-4dc7-9972-c6a86282716c.webp" alt="Documentation video still of the Next.js e-commerce template: starting the admin dashboard without Docker" /></p>
<p>The admin dashboard runs in its own terminal on port 3031, beside the storefront on 3030.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/2517e5f0-7813-4244-a628-846654b84bd1.jpg" alt="Admin dashboard overview in the Next.js e-commerce template, light theme" /></p>
<p>The screenshot above is the admin overview you should see after signing in as the Super Admin.</p>
<p><strong>What to check:</strong> open <code>localhost:8000/api/health</code>, which should answer with a status of ok. Then add a product to the cart as the demo customer, check out as a guest, and find the order in the admin.</p>
<p><strong>What usually goes wrong:</strong></p>
<ul>
<li><p>Docker is not running, or port 3030, 3031 or 8000 is taken. Free it, or set <code>SITE_PORT</code>, <code>ADMIN_PORT</code> or <code>API_PORT</code> to a free number.</p>
</li>
<li><p>The first start seems stuck. It is seeding the demo store, and the frontends start only when the API is healthy.</p>
</li>
<li><p>A "Sample data" notice shows. The frontend was built without an API address and is running on its own sample store.</p>
</li>
<li><p>Yarn reports version 1.22. Run <code>corepack enable</code> and install again.</p>
</li>
</ul>
<h3>Step 3: Make it Cedar &amp; Cloth</h3>
<p>The brand lives in files, and the storefront and the admin keep their own copies. In the storefront, <code>src/config/brand.config.ts</code> holds the store name (it ships as a text wordmark), the browser tab name, the contact details and the social links, each with English and Arabic values. Set <code>NEXT_PUBLIC_SITE_URL</code> to your real domain, because canonical links, the sitemap and sharing cards use it.</p>
<p>The shipped copy describes a menswear shop. Three places carry that copy: the text blocks in <code>brand.config.ts</code>, the <code>messages/home/</code> folder for the home page, and <code>messages/seo/</code> for page titles. Cedar &amp; Cloth sells menswear too, so it edits less than most shops will.</p>
<p>Each app keeps its colors in <code>src/styles/theme-variables.css</code>, as CSS variables, with a block for light and a block for dark. The accent is <code>--primaryColor</code>. The storefront loads Plus Jakarta Sans for Latin text and two Arabic fonts. The admin has its own brand file and uses the system font stack.</p>
<p><strong>What to check:</strong> rebuild, then look for the old name in the browser tab, the footer, the sharing preview and the Arabic pages. Replace the placeholder contact details, since they ship as placeholders.</p>
<p><strong>What usually goes wrong:</strong> the footer shows no social icons, because the links ship empty and only filled ones appear. Another is a sharing image that still shows the template's hero photo. Point <code>meta.ogImage</code> at your own picture.</p>
<h3>Step 4: Add categories and products</h3>
<p>Start with categories: a name and description in both languages, plus an image, a slug, a sort position and an on/off switch. They are one flat level. Then add products. A product takes:</p>
<ul>
<li><p>A name and descriptions in both languages (only the English name is mandatory), a slug, a SKU and a category.</p>
</li>
<li><p>A price, an optional compare-at price, a cost price and a stock count.</p>
</li>
<li><p>Up to 12 images and videos in any order, one marked primary, each with alt text.</p>
</li>
<li><p>Variants such as Size with M, or Colour with its hex code. Each variant has its own SKU, price adjustment and stock.</p>
</li>
<li><p>Flags for active, featured and best seller, and free tags.</p>
</li>
</ul>
<p>Uploads go to a Cloudflare R2 bucket, or another S3-compatible store, and fail with a 503 until you fill in the five <code>R2_*</code> variables in <code>back-end/.env</code>. The demo catalogue itself renders from bundled files, so you can build the whole flow before you set a bucket.</p>
<p>Work in this order, so nothing points at something that does not exist yet:</p>
<ol>
<li><p>Create categories first, since every product needs one.</p>
</li>
<li><p>Add one complete product, with photos, variants and both languages, before you add the rest.</p>
</li>
<li><p>Open it on the storefront in English and Arabic and check the gallery, the variant picker and the price.</p>
</li>
<li><p>Only then repeat for the remaining products.</p>
</li>
</ol>
<p><img src="https://cdn-aniq-ui.com/blog/images/ce6827d2-f669-46a0-844d-103af8d9d2cc.jpg" alt="Products management screen in the Next.js e-commerce admin dashboard, light theme" /></p>
<p><img src="https://cdn-aniq-ui.com/blog/images/954f4929-a0ca-40ac-a812-b77e941f741c.jpg" alt="Categories screen in the Next.js e-commerce admin dashboard, light theme" /></p>
<p>Look at the flat list of categories with their order and active switch: the sort order here shapes the categories row on the home page.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/5d547d54-04c7-483d-9540-c2665d8a89ce.jpg" alt="Products management in compact view, Next.js e-commerce admin dashboard" /></p>
<p>The compact view fits more rows on screen, which helps when you are checking stock and prices across many products.</p>
<p><strong>What to check:</strong> deleted products have their own list, so check where one lands after you remove it. Variant SKUs must be unique, so use a clear naming pattern from the start.</p>
<p><strong>What usually goes wrong:</strong> uploads fail with a 503, because the bucket variables are not set. Or images load at full size, because the frontends were not told your bucket's public host. Set <code>NEXT_PUBLIC_MEDIA_HOSTNAME</code> to that host, without <code>https://</code>, and rebuild.</p>
<h3>Step 5: Arrange the home page</h3>
<p>The Home Page screen in the admin decides, one section at a time, what shoppers see on the storefront's front page. Categories need only an order. The other sections take a capped number of products or texts: up to 3 style pillars, 2 editorial panels, 6 new drops, 8 best sellers, 6 spotlight items and 5 slides in the closing slider. If New drops is empty, it shows the newest products. Editing a section needs the <code>products.edit</code> permission.</p>
<p><strong>What to check:</strong> add a product that uses every section, then open the storefront home page and confirm each section shows what you picked. Empty the New drops section and confirm it falls back to the newest products.</p>
<p><strong>What usually goes wrong:</strong> a change does not appear because you lack the <code>products.edit</code> permission, or because the storefront is on its sample store and not reading the API.</p>
<h3>Step 6: Set shipping, payments and the order flow</h3>
<p>The checkout offers card through Stripe, and cash on delivery. Cash on delivery is selected by default, and the API always prices an order from its own catalogue, never from numbers the browser sends. There is no PayPal option.</p>
<p>The shipping rule ships as free from $75 and $9.99 below that, with no tax. It is written in two places, <code>storefront/src/config/shipping.ts</code> and <code>back-end/src/modules/orders/orders.service.ts</code>. Edit both in one change, or the cart and the charge will disagree.</p>
<p>To take cards, use Stripe test keys first:</p>
<ol>
<li><p>Add both <code>STRIPE_SECRET_KEY</code> and <code>STRIPE_WEBHOOK_SECRET</code> to <code>back-end/.env</code>.</p>
</li>
<li><p>Put <code>NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY</code> in the storefront's <code>.env</code> and rebuild.</p>
</li>
<li><p>In the Stripe dashboard, create a webhook endpoint that points to your API address plus <code>/api/payments/webhook</code>, and have it listen for two events: <code>payment_intent.succeeded</code> and <code>payment_intent.payment_failed</code>.</p>
</li>
</ol>
<p>A card order stays pending until Stripe calls that webhook, then becomes paid and confirmed. For local testing, the Stripe CLI can relay events to <code>http://localhost:8000/api/payments/webhook</code>. In the admin, an order moves one step at a time: pending, confirmed, processing, shipped, delivered, or cancelled before it closes. Add the tracking number when you ship, and download any order as a CSV file.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/d5948b7b-ca63-4d76-bc32-37d396e75d48.jpg" alt="Orders list with fulfilment progress in the Next.js e-commerce admin dashboard" /></p>
<p><strong>What to check:</strong> place a cash on delivery order and a card order with Stripe test keys. The first should be confirmed and unpaid. The second should be pending until the webhook arrives, then paid and confirmed. Fail a card on purpose and confirm the order is marked failed.</p>
<p><strong>What usually goes wrong:</strong></p>
<ul>
<li><p>The card option is missing at checkout. The publishable key is empty or not a real test or live key, which leaves cash on delivery as the only choice.</p>
</li>
<li><p>Card orders stay pending. The webhook endpoint or its signing secret is wrong.</p>
</li>
<li><p>The storefront still shows the old publishable key. It is compiled in, so rebuild after changing it.</p>
</li>
</ul>
<h3>Step 7: Add staff and set their permissions</h3>
<p>Staff accounts live under Admin Management, and their permissions under Admin Roles. The seed gives you a Super Admin with every permission and a Viewer role with every view permission, which leaves out the AI assistant. The Admin, Manager and Editor roles exist but start with nothing, so tick their permissions before you give them to anyone.</p>
<p>Cedar &amp; Cloth keeps the owner as Super Admin. For the two packers it gives view access to orders, plus the edit permission that moving an order forward requires. Everything else stays hidden from them, because the sidebar and the API check the same permission names.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/9ea93f8b-2f43-447e-8712-8e39fd3c45e4.jpg" alt="Roles and permissions screen in the Next.js e-commerce admin dashboard" /></p>
<p><strong>What to check:</strong> sign in as the Viewer account and confirm it can see lists but not change them. Then sign in as the packer role you created and confirm moving an order forward works.</p>
<p><strong>What usually goes wrong:</strong> a new staff member sees almost nothing, because their role has no permissions ticked. Permission changes reach signed-in staff over a live connection, so they do not need to sign out.</p>
<h3>Step 8: Add the AI tools you want</h3>
<p>Each AI feature switches on only when its key is in <code>back-end/.env</code>, and a key still holding its example value counts as unset.</p>
<ul>
<li><p><strong>Admin assistant:</strong> needs a Google Gemini key. It answers questions about the shop, finds orders, edits products and stock, and draws sales charts, all within the signed-in admin's permissions.</p>
</li>
<li><p><strong>AI product studio:</strong> in the product form. Its assistant mode needs a Gemini key and the media bucket. Its Animate mode needs a Higgsfield key and secret.</p>
</li>
<li><p><strong>Fitting room:</strong> lets shoppers see a product worn on a model or on their own photo. It needs a Gemini key and the bucket.</p>
</li>
<li><p><strong>Background removal:</strong> needs a model file on your own server and the bucket, but no key, and it costs nothing per image.</p>
</li>
</ul>
<p>Cedar &amp; Cloth turns on only background removal, so the phone shots become clean catalogue photos. The Docker image leaves the model out unless you ask for it when you build. Provider charges for the keyed features are yours.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/1e3c4145-198e-458b-a45c-88536707e149.jpg" alt="AI assistant sales report in the Next.js e-commerce admin dashboard, light theme" /></p>
<p><strong>What to check:</strong> open the AI Assistant page and ask for a sales summary. Confirm the answer comes with a chart drawn from your own data. For background removal, open a product photo and confirm the Remove background button appears.</p>
<p><strong>What usually goes wrong:</strong> a feature reports itself off. Either its key is missing or still holds the example value, or it needs the media bucket as well. The studio, the fitting room and background removal all need the bucket. Also remember that the assistant and the studio are unavailable on the sample store.</p>
<h3>Step 9: Wire up analytics</h3>
<p>Six ad and analytics networks are built into the storefront. Paste an id into <code>storefront/.env</code> and rebuild. A blank id loads no script. The variables are <code>NEXT_PUBLIC_GTM_ID</code>, <code>NEXT_PUBLIC_GA4_MEASUREMENT_ID</code>, <code>NEXT_PUBLIC_META_PIXEL_ID</code>, <code>NEXT_PUBLIC_TIKTOK_PIXEL_ID</code>, <code>NEXT_PUBLIC_SNAPCHAT_PIXEL_ID</code> and <code>NEXT_PUBLIC_PINTEREST_TAG_ID</code>.</p>
<p>If you set only one, make it Google Tag Manager, which can load the others itself. If GA4 already runs inside your Tag Manager container, leave the GA4 variable blank, or every session counts twice. The storefront reports page views, product views, add to cart, begin checkout, purchase, search and sign-up. Set <code>NEXT_PUBLIC_ANALYTICS_DEBUG=true</code> to log each event in the browser console while testing.</p>
<p>The tags load as soon as a page does. If you sell to the EU or the UK, show a consent banner before they run.</p>
<p><strong>What to check:</strong> turn on debug logging, click through a purchase and watch the events appear in the browser console in order: product view, add to cart, begin checkout, purchase. Then confirm the same events in Tag Manager's preview or your analytics tool.</p>
<p><strong>What usually goes wrong:</strong> a change to an id has no effect, since ids are compiled in and need a rebuild. Or the purchase event fires without the right currency. Set <code>NEXT_PUBLIC_ANALYTICS_CURRENCY</code> if you do not sell in US dollars.</p>
<h3>Step 10: Go live</h3>
<p>Fix the gaps the template leaves open, then deploy:</p>
<ul>
<li><p>It sends no email at all: no order confirmation, no shipping notice, no password reset. Connect a mail provider in the <code>forgotPassword</code> hook of <code>back-end/src/modules/customer-auth/customer-auth.controller.ts</code> and for orders.</p>
</li>
<li><p>Both the contact form and the newsletter signup acknowledge the visitor yet deliver nothing, and no terms or privacy pages come with the template. Connect the forms and write the pages.</p>
</li>
</ul>
<p>Then configure the API in <code>back-end/.env</code>: a fresh <code>JWT_SECRET</code> (made with <code>node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"</code>), <code>NODE_ENV=production</code>, <code>CORS_ORIGIN</code> listing the storefront and admin addresses, and <code>FRONTEND_URL</code> set to the admin's address. Build the API, run <code>yarn db:sync:prod</code> once to create the tables, and start it. In each frontend set <code>NEXT_PUBLIC_API_BASE_URL</code> with <code>/api</code> on the end and rebuild. Set <code>NEXT_PUBLIC_STOREFRONT_URL</code> in the admin so its Go to storefront link works.</p>
<p>Do not use <code>yarn railway:setup</code> for a live shop: it drops every table each time it runs. Change the published demo passwords, or start from empty tables.</p>
<p><strong>What to check after going live:</strong> place a real small order on your domain, watch it appear in the admin with a notification, move it through its statuses, and track it as a guest with the order number and email. Confirm the notification bell is live, which means the admin's address matches <code>FRONTEND_URL</code>.</p>
<p><strong>What usually goes wrong:</strong></p>
<ul>
<li><p>Browsers are blocked by the API. <code>CORS_ORIGIN</code> must list both frontends exactly as the browser shows them.</p>
</li>
<li><p>Everyone gets "Too many attempts" behind a proxy. Each of those routes (sign-in, registration, password reset, guest tracking) accepts ten requests a minute from one address. Set <code>TRUST_PROXY</code> to how many proxies stand in front.</p>
</li>
<li><p>Password reset goes nowhere. In production the reset token is not delivered until you connect a mail provider.</p>
</li>
</ul>
<h2>Running it day to day</h2>
<p>When the shop is live, the owner and packers use a short list of admin screens.</p>
<h3>Starting the day on the overview</h3>
<p>The overview sits at the top of the sidebar and shows the shop at a glance. Remember that several cards display placeholder figures until you connect real numbers, so keep a separate, trusted source for revenue until you do.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/d01e8986-d7e6-4374-8477-6367f8fafa3c.jpg" alt="Admin dashboard overview of the Next.js e-commerce template in the dark theme" /></p>
<p>Look at the latest orders and the bell in the top bar, which is where new activity shows first.</p>
<h3>Moving orders along</h3>
<p>Filter the list by order status or payment status; the newest orders come first. Open an order, check the items, totals and addresses, add the tracking number when it ships, and move it forward one step. Cancel only before the order is closed. The payment status is set by the payment, never by hand.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/814fc6d6-9bbf-4aa6-85e1-6da41bea7176.jpg" alt="Orders with fulfilment progress in the dark theme, Next.js e-commerce admin dashboard" /></p>
<p>The fulfilment progress on each row shows how far an order has moved, so packers can scan for what is still waiting.</p>
<h3>Helping a customer</h3>
<p>The customers screen lists the shop's customers, and deleted ones have their own list. A customer who cannot track an order needs the exact order number and the email used at checkout, because tracking asks for both.</p>
<p><img src="https://cdn-aniq-ui.com/blog/images/1e09e2cb-86b5-48bd-8bbd-964a354fdbd7.jpg" alt="Customer accounts screen in the Next.js e-commerce admin dashboard" /></p>
<p>Use this list to find a customer by account and open their record when they write to you.</p>
<h3>Keeping the storefront fresh</h3>
<p>Rearrange the home page sections when you launch a new product, add an offer, or want a best seller pushed forward. Those edits are made in the admin, so they need no code change.</p>
<h3>Settings are stored values</h3>
<p>The App settings tab holds key and value pairs, including payment, email and general ones. The shipped storefront and API do not read them yet, so changing one changes nothing until your own code does.</p>
<h2>An example launch plan by week</h2>
<p>This schedule is an example for Cedar &amp; Cloth, not a promise about how long your launch will take.</p>
<ul>
<li><p><strong>Week 1, understand.</strong> Run the stack, place a test order, and settle the decisions list.</p>
</li>
<li><p><strong>Week 2, brand and catalogue.</strong> Rebrand both apps, rewrite the shipped copy, and add categories and one complete product.</p>
</li>
<li><p><strong>Week 3, the rest of the shop.</strong> Add the remaining products, arrange the home page, and set up bucket storage and photos.</p>
</li>
<li><p><strong>Week 4, money and staff.</strong> Set the shipping rule, connect Stripe in test mode, create the roles for the packers, and run orders through every status.</p>
</li>
<li><p><strong>Week 5, production.</strong> Set up hosting, the environment files and the tables. Connect a mail provider, add tracking tags, and write the missing terms and privacy pages.</p>
</li>
<li><p><strong>Week 6, soft launch.</strong> Start with a small audience, then switch to Stripe live keys when you are sure.</p>
</li>
</ul>
<h2>Launch checklist</h2>
<ul>
<li><p>Store name, logos, icons, colors and fonts replaced in both apps.</p>
</li>
<li><p>Shipped menswear copy rewritten in the brand file, the home messages and the SEO messages.</p>
</li>
<li><p>Contact details, social links and sharing images replaced.</p>
</li>
<li><p>Categories and products complete in both languages, with variants and photos.</p>
</li>
<li><p>Shipping rule changed in both files, if you changed it at all.</p>
</li>
<li><p>Stripe live keys and the live webhook in place, after a full test-mode run.</p>
</li>
<li><p>Roles ticked for each staff member, and the demo passwords changed.</p>
</li>
<li><p><code>JWT_SECRET</code>, <code>CORS_ORIGIN</code>, <code>FRONTEND_URL</code> and both frontend API addresses set for production.</p>
</li>
<li><p><code>NEXT_PUBLIC_SITE_URL</code> set to the real domain.</p>
</li>
<li><p>A mail provider connected, and the contact form and newsletter form wired.</p>
</li>
<li><p>Terms and privacy pages written.</p>
</li>
<li><p>Tracking ids pasted, and a consent banner added if you sell to the EU or UK.</p>
</li>
<li><p>Demo checkout prefill left off.</p>
</li>
<li><p>Backups scheduled for the database and the media bucket.</p>
</li>
</ul>
<h2>Template, from scratch, or a hosted store builder</h2>
<h3>A hosted store builder</h3>
<p>You can be selling quickly, with hosting, checkout and updates handled for you. You pay ongoing fees, work within the platform's design and rules, and keep your data on their system. It suits a shop that wants to sell, not to run software.</p>
<h3>Building from scratch</h3>
<p>You get exactly what you design. You also build a catalogue with variants, carts, guest checkout, order tracking, payment and webhooks, accounts for customers and staff, permissions, an admin, two languages and an API before the first order. You maintain all of it.</p>
<h3>Starting from a template</h3>
<p>You own the code, host the stack and change anything. The storefront, admin and API are already connected, so you spend your time on products and brand. In return you accept the work this guide lists: email, tax rules, terms pages, hosting and updates. It suits founders who want control, and agencies building stores for clients.</p>
<h2>What it costs to run</h2>
<p>Template packages start from $79, and the Full Stack package Cedar &amp; Cloth uses is $179. It includes a commercial license and lifetime support. Beyond that you pay for what you switch on:</p>
<ul>
<li><p>Hosting for the storefront, admin and API, and a database if you move past SQLite.</p>
</li>
<li><p>Stripe's processing fees, listed on <a href="https://stripe.com/pricing">Stripe's pricing page</a>. Cash on delivery needs no processor.</p>
</li>
<li><p>A bucket such as Cloudflare R2 for product images.</p>
</li>
<li><p>A Google Gemini key for the assistant, studio or fitting room, billed by Google, and a Higgsfield account for video.</p>
</li>
<li><p>A mail provider and a domain.</p>
</li>
</ul>
<p>Free parts: SQLite for local work, the demo store, cash on delivery, and background removal on your own server.</p>
<h2>What to customise next</h2>
<ul>
<li><p><strong>Copy and photos.</strong> Replace the home page messages and the page titles in both languages.</p>
</li>
<li><p><strong>Shipping rules.</strong> Change the free-shipping threshold or fee in the two files together.</p>
</li>
<li><p><strong>Another tracking network.</strong> The marketing tags are configured in <code>src/config/analytics.config.ts</code>, and the template describes adding one more as a single-file job.</p>
</li>
<li><p><strong>Admin overview cards.</strong> Wire the sample revenue and conversion cards to your own numbers.</p>
</li>
<li><p><strong>Roles.</strong> Build a role for each person on the team.</p>
</li>
<li><p><strong>A third language.</strong> Add it to both frontends and the API. Products hold two languages, English and Arabic.</p>
</li>
</ul>
<h2>Common mistakes</h2>
<h3>Card orders that stay pending</h3>
<p>An order flips to paid only after Stripe's webhook reaches your API; the shopper coming back to the site does not do it. Check the endpoint address, the two subscribed events and the signing secret.</p>
<h3>Changing the shipping rule in only one place</h3>
<p>The cart, checkout summary and API must agree. Edit the storefront config and the orders service in the same change.</p>
<h3>Leaving the frontends on the sample store</h3>
<p>Without <code>NEXT_PUBLIC_API_BASE_URL</code>, each frontend answers from sample data in the browser, shows a notice, and charges no one. Set the address and rebuild.</p>
<h3>Counting every GA4 session twice</h3>
<p>If GA4 loads from Tag Manager, leave the template's GA4 variable empty.</p>
<h3>Handing out an empty role</h3>
<p>Admin, Manager and Editor start with no permissions. A staff member given one sees almost nothing until you tick what they need.</p>
<h2>FAQ</h2>
<h3>How do I build an online store with an admin panel in Next.js?</h3>
<p>Use a template that already has the storefront, the dashboard and the API as one project, and change the brand and catalogue. This one gives you all three, with a seeder that fills the database with a demo store in one command.</p>
<h3>Can I use it for clients?</h3>
<p>Yes. The license covers unlimited projects, including stores built for a customer and handed over. You may not resell the code or release it as a template.</p>
<h3>Does it support Arabic and RTL?</h3>
<p>Yes. The storefront, the admin and the API ship in English and Arabic, with Arabic laid out right to left. Products and categories are stored with both languages.</p>
<h3>Do I need a backend?</h3>
<p>For real orders, yes. The frontends run alone on a sample store, but real orders, payments and AI features depend on the NestJS API, which comes with the Full Stack and Backend API packages.</p>
<h3>Does it support guest checkout?</h3>
<p>Yes. Guests check out with an email and track the order by number and email, with no account.</p>
<h3>Which payment methods work?</h3>
<p>Card payments run on Stripe, and shoppers can also choose cash on delivery. PayPal is not offered at checkout.</p>
<h3>Which database does it use?</h3>
<p>SQLite for local work and MySQL by configuration, with no code change.</p>
<h3>Does it handle tax?</h3>
<p>No. The shipping rule and checkout total apply no tax. If your business must charge it, add that to the pricing logic on both the storefront and the API so the totals stay equal.</p>
<h3>Can customers pay in other currencies?</h3>
<p>Card payments are charged in US dollars. Selling in another currency means changing that in code, and the tracking currency is a separate setting.</p>
<h3>What happens when a card is declined?</h3>
<p>The order is marked failed when Stripe reports the failed payment. Cash on delivery remains available for that customer.</p>
<h2>Try it yourself</h2>
<p>Open the <a href="https://ecommerce-clothes-1.aniq-ui.com/en">storefront demo</a> and the <a href="https://ecommerce-clothes-1-admin.aniq-ui.com/en/dashboard">admin demo</a>. Then read the <a href="https://www.aniq-ui.com/en/templates/next-js-ecommerce-template/docs">documentation</a> or visit the <a href="https://www.aniq-ui.com/en/templates/next-js-ecommerce-template">e-commerce template page</a>. More choices are in the <a href="https://www.aniq-ui.com/en/templates/category/ecommerce-nextjs-online-store-templates">e-commerce templates</a> category and the <a href="https://www.aniq-ui.com/en/blog/nextjs-ecommerce-templates">Next.js e-commerce templates guide</a>.</p>
<p>The e-commerce template is also one of the ten templates in the <a href="https://www.aniq-ui.com/en/templates/nextjs-templates-bundle">Next.js Templates Bundle</a>.</p>
]]></content:encoded></item><item><title><![CDATA[Tailwind CSS RTL in Next.js: logical utilities, the rtl: variant and what must never flip]]></title><description><![CDATA[Set dir on html, use logical utilities like ms-4, keep rtl: for what they cannot express. A practical Tailwind CSS RTL guide for Next.js.]]></description><link>https://aniqui.hashnode.dev/tailwind-css-rtl-nextjs</link><guid isPermaLink="true">https://aniqui.hashnode.dev/tailwind-css-rtl-nextjs</guid><category><![CDATA[Tailwind CSS]]></category><category><![CDATA[Next.js]]></category><category><![CDATA[CSS]]></category><category><![CDATA[i18n]]></category><dc:creator><![CDATA[Aniq UI]]></dc:creator><pubDate>Thu, 12 Nov 2026 20:43:42 GMT</pubDate><content:encoded><![CDATA[<p>We ship every Next.js template in English and Arabic, with a real right-to-left layout. After doing that across every website and dashboard we sell, the whole approach fits in one sentence:</p>
<blockquote>
<p>Set <code>dir</code> on <code>&lt;html&gt;</code>, write spacing and position with logical utilities (<code>ms-4</code>, not <code>ml-4</code>), and keep the <code>rtl:</code> variant for the few things logical properties cannot express.</p>
</blockquote>
<p>This post is the practical version of that sentence, with code from real projects. Every class below was checked against Tailwind CSS 4.3.</p>
<h2>1. Put dir on <code>&lt;html&gt;</code>, on the server</h2>
<p>Logical properties read the element's direction, the <code>rtl:</code> variant looks for it, and screen readers use <code>lang</code> to pick a voice. Put both on <code>&lt;html&gt;</code>, not on a wrapper: dialogs, menus and toasts usually render in a portal under <code>&lt;body&gt;</code> and only inherit a direction set above them.</p>
<p>With next-intl and the App Router, let <code>app/[locale]/layout.tsx</code> render <code>&lt;html&gt;</code>:</p>
<pre><code class="language-ts">// src/config/i18n.ts
export const directionOf = (locale: string): "rtl" | "ltr" =&gt;
  locale === "ar" ? "rtl" : "ltr";
</code></pre>
<pre><code class="language-tsx">// src/app/[locale]/layout.tsx (trimmed)
export default async function LocaleLayout({ children, params }: {
  children: React.ReactNode;
  params: Promise&lt;{ locale: string }&gt;;
}) {
  const { locale } = await params;
  if (!hasLocale(routing.locales, locale)) notFound();
  setRequestLocale(locale);
  const messages = await getMessages();

  return (
    &lt;html lang={locale} dir={directionOf(locale)} suppressHydrationWarning&gt;
      &lt;body&gt;
        &lt;NextIntlClientProvider messages={messages}&gt;{children}&lt;/NextIntlClientProvider&gt;
      &lt;/body&gt;
    &lt;/html&gt;
  );
}
</code></pre>
<p><strong>Do not set <code>dir</code> in a <code>useEffect</code>.</strong> The server HTML then arrives left to right, paints that way, and flips after hydration: a visible jump on every Arabic page load.</p>
<h2>2. Logical utilities do most of the work</h2>
<p><code>ml-4</code> is <code>margin-left</code> in both languages. <code>ms-4</code> is <code>margin-inline-start</code>: the left in English, the right in Arabic. One class, both directions.</p>
<table>
<thead>
<tr>
<th>Physical</th>
<th>Logical</th>
<th>CSS</th>
</tr>
</thead>
<tbody><tr>
<td><code>ml-4</code> / <code>mr-4</code></td>
<td><code>ms-4</code> / <code>me-4</code></td>
<td><code>margin-inline-start</code> / <code>-end</code></td>
</tr>
<tr>
<td><code>pl-4</code> / <code>pr-4</code></td>
<td><code>ps-4</code> / <code>pe-4</code></td>
<td><code>padding-inline-start</code> / <code>-end</code></td>
</tr>
<tr>
<td><code>left-0</code> / <code>right-0</code></td>
<td><code>inset-s-0</code> / <code>inset-e-0</code> (or <code>start-0</code> / <code>end-0</code>)</td>
<td><code>inset-inline-start</code> / <code>-end</code></td>
</tr>
<tr>
<td><code>text-left</code></td>
<td><code>text-start</code></td>
<td><code>text-align: start</code></td>
</tr>
<tr>
<td><code>border-l</code></td>
<td><code>border-s</code></td>
<td><code>border-inline-start-width</code></td>
</tr>
<tr>
<td><code>rounded-l-lg</code></td>
<td><code>rounded-s-lg</code></td>
<td>the two start corners</td>
</tr>
</tbody></table>
<p>Tailwind CSS 4.2 added <code>inset-s-*</code> and <code>inset-e-*</code> and deprecated <code>start-*</code> and <code>end-*</code>. The old names still compile to the same property, so existing code is fine.</p>
<p><strong>What already flips without a new class:</strong> flex and grid rows, <code>justify-start</code> / <code>justify-end</code>, <code>mx-*</code>, <code>px-*</code>, and in Tailwind CSS 4 also <code>space-x-*</code> and <code>divide-x</code>. So never add <code>flex-row-reverse</code> "for Arabic": the row already reversed when the direction changed, and reversing it again puts it back in English order.</p>
<p>An input with an icon shows the pattern in one component:</p>
<pre><code class="language-tsx">&lt;div className="relative"&gt;
  &lt;span className="pointer-events-none absolute start-4 top-1/2 -translate-y-1/2"&gt;
    {startIcon}
  &lt;/span&gt;
  &lt;input className="h-12 ps-11" {...props} /&gt;
&lt;/div&gt;
</code></pre>
<p>Icon at <code>start-4</code>, text padded with <code>ps-11</code>. In Arabic both move to the right with no override.</p>
<p>Physical utilities are still right when the thing is physical: <code>left-1/2 -translate-x-1/2</code> centres in both directions, and a before/after photo slider keeps "before" on the left in every language. Decide per element, and leave a comment so nobody "fixes" it later.</p>
<h2>3. The rtl: variant, for what logical properties cannot express</h2>
<p>Transforms, gradients, transform origins, keyframes and icon meaning have no logical version. That is what <code>rtl:</code> and <code>ltr:</code> are for. In Tailwind CSS 4.3 they compile like this:</p>
<pre><code class="language-css">.rtl\:-scale-x-100:where(:dir(rtl), [dir="rtl"], [dir="rtl"] *) {
  --tw-scale-x: calc(100% * -1);
  scale: var(--tw-scale-x) var(--tw-scale-y);
}
</code></pre>
<p>The <code>:where()</code> adds no specificity, and the selector matches the element's own direction, a <code>dir="rtl"</code> attribute, <strong>or any ancestor</strong> with <code>dir="rtl"</code>. Keep that last part in mind (see the catch below).</p>
<p><strong>Direction icons:</strong></p>
<pre><code class="language-tsx">// Mirror a "next" arrow in Arabic
&lt;IconArrowRight aria-hidden className="h-5 w-5 rtl:-scale-x-100" /&gt;
</code></pre>
<p>Prefer <code>-scale-x-100</code> (a true mirror) over <code>rotate-180</code>, which also turns the icon upside down. Flip arrows, chevrons and "view all" links. Do not flip play buttons, media progress bars, clocks or logos.</p>
<p><strong>translate-x is physical,</strong> so anything that slides off screen needs a variant:</p>
<pre><code class="language-tsx">// A mobile menu that slides in from the inline start
&lt;div className={cn(
  "absolute top-0 start-0 h-full w-64 rounded-e-xl transition-transform",
  isOpen ? "translate-x-0" : "ltr:-translate-x-full rtl:translate-x-full",
)} /&gt;
</code></pre>
<p><strong>Gradients have no logical direction</strong> in Tailwind CSS 4.3:</p>
<pre><code class="language-tsx">&lt;div className="absolute inset-0 bg-linear-to-r from-black/85 to-transparent rtl:bg-linear-to-l" /&gt;
</code></pre>
<p><strong>Transform origin</strong> too: a progress bar should grow from the side the text starts on, <code>ltr:origin-left rtl:origin-right</code>.</p>
<p><strong>Keyboard arrows are behaviour.</strong> In tabs or a slider, the right arrow key should move towards the next item on screen, which is to the left in Arabic:</p>
<pre><code class="language-ts">const isRtl = useLocale() === "ar";
const forward = isRtl ? "ArrowLeft" : "ArrowRight";
</code></pre>
<h3>The catch: rtl: still matches inside a dir="ltr" island</h3>
<p>Because <code>rtl:</code> matches any <code>dir="rtl"</code> ancestor, it still applies inside a <code>dir="ltr"</code> element on an Arabic page. When you need the element's own direction, use an arbitrary variant on the <code>:dir()</code> pseudo-class:</p>
<pre><code class="language-tsx">&lt;IconChevronRight className="[&amp;:dir(rtl)]:-scale-x-100" /&gt;
</code></pre>
<h2>4. What must never flip</h2>
<p>Mixed runs of digits and punctuation take the direction of the Arabic around them, so phone numbers, prices and counters like <code>3 / 12</code> can come out scrambled. Isolate them.</p>
<p><strong>Latin digits in Arabic:</strong> ask for them explicitly, because the region decides otherwise:</p>
<pre><code class="language-js">new Intl.NumberFormat("ar-SA").format(1248.6);           // "١٬٢٤٨٫٦"
new Intl.NumberFormat("ar-SA-u-nu-latn").format(1248.6); // "1,248.6"
</code></pre>
<p><strong>Prices:</strong></p>
<pre><code class="language-tsx">&lt;bdi dir="ltr" className="tabular-nums"&gt;{formatPrice(price, currency)}&lt;/bdi&gt;
</code></pre>
<p><strong>Phone, email, URLs:</strong> typed and shown left to right, but aligned with the Arabic form:</p>
<pre><code class="language-tsx">&lt;Input type="tel" dir="ltr" className="rtl:text-end" {...register("phone")} /&gt;
&lt;a href={`mailto:${email}`} dir="ltr"&gt;{email}&lt;/a&gt;
</code></pre>
<p><strong>Text written by users</strong> can be either language, so let the browser decide: <code>&lt;p dir="auto"&gt;{review.body}&lt;/p&gt;</code>.</p>
<p>Code blocks and Latin logos stay <code>dir="ltr"</code>. Photos are never mirrored.</p>
<h2>5. Arabic type: font, line height, letter spacing</h2>
<p>Many Latin UI fonts have no Arabic glyphs, so load one font per script with <code>next/font</code> and switch under <code>[dir="rtl"]</code>, Arabic first so Latin words inside Arabic text fall through to your Latin font:</p>
<pre><code class="language-css">[dir="rtl"] body {
  font-family: var(--font-arabic), var(--font-inter), system-ui, sans-serif;
  letter-spacing: 0;
}
</code></pre>
<ul>
<li><strong>Line height:</strong> a <code>leading-[1.1]</code> display heading can clip Arabic ascenders and diacritics. Open it up in Arabic only: <code>leading-[1.1] rtl:leading-[1.4]</code>.</li>
<li><strong>Letter spacing:</strong> Arabic is a connected script, and tracking makes it look broken. Reset it with <code>rtl:tracking-normal</code>.</li>
<li><strong>Uppercase</strong> does nothing in Arabic, so an eyebrow label that relies on caps needs weight or colour instead.</li>
</ul>
<h2>6. A short RTL test pass</h2>
<p>Run it on every page in Arabic, light and dark, phone and desktop:</p>
<ol>
<li>View source (not the inspector): <code>&lt;html lang="ar" dir="rtl"&gt;</code> is in the server HTML, and nothing flips after load.</li>
<li>Sidebar, logo and main action sit on the right. Nothing is reversed twice.</li>
<li>Drawers, menus and toasts open from the correct side, portals included.</li>
<li>Arrows point the right way; play buttons and clocks do not flip.</li>
<li>Phone, email and code fields type left to right.</li>
<li>Prices, phone numbers and counters read in the right order.</li>
<li>The Arabic font actually loads, headings do not clip, no Arabic letter spacing.</li>
<li>Arrow keys in tabs and sliders follow the screen.</li>
</ol>
<p>Then search for physical classes and decide on each hit:</p>
<pre><code class="language-bash">grep -rnE --include='*.tsx' \
  '(^|[^a-z0-9-])-?(ml|mr|pl|pr|left|right)-([0-9]|\[|\(|px|auto|full)|(^|[^a-z0-9-])(rounded|border)-(l|r|tl|tr|bl|br)([^a-z0-9]|-|$)|(^|[^a-z0-9-])(text|float)-(left|right)([^a-z0-9-]|$)' \
  src
</code></pre>
<p>On our apps it returns between 2 and 10 lines per app (centred elements, symmetric pairs, a physical slider, lines that already carry an <code>rtl:</code> override). Short enough to read every line, which is the point.</p>
<hr />
<p>The full guide, with the next-intl routing and proxy setup, charts and time axes, <code>unicode-bidi</code>, self-hosted Arabic fonts and an FAQ, is on our blog: <a href="https://www.aniq-ui.com/en/blog/tailwind-css-rtl">Tailwind CSS RTL Guide: Logical Properties and the rtl: Variant</a>.</p>
<p>If you would rather start from code where this is already done: our Next.js templates ship in English and Arabic with full RTL. Websites and landing pages are $39, dashboards from $49, and full stack packages (website, dashboard and NestJS API) are $149, paid once. You can switch every live demo to Arabic at <a href="https://www.aniq-ui.com/en/templates">aniq-ui.com</a>.</p>
]]></content:encoded></item></channel></rss>