> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tailor-platform/app-shell/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Complete installation guide for AppShell including peer dependencies, package manager setup, and authentication configuration.
This guide covers everything you need to install and configure AppShell in your React application.
## Package installation
Install AppShell using your preferred package manager:
```bash npm theme={null}
npm install @tailor-platform/app-shell
```
```bash yarn theme={null}
yarn add @tailor-platform/app-shell
```
```bash pnpm theme={null}
pnpm add @tailor-platform/app-shell
```
## Peer dependencies
AppShell requires React 19 or later as peer dependencies. Make sure you have them installed:
```bash npm theme={null}
npm install react@19 react-dom@19
```
```bash yarn theme={null}
yarn add react@19 react-dom@19
```
```bash pnpm theme={null}
pnpm add react@19 react-dom@19
```
AppShell requires React 19 or later. It is built with React 19 features and optimizations.
### Peer dependency details
AppShell's `package.json` specifies:
```json theme={null}
"peerDependencies": {
"react": ">= 19",
"react-dom": ">= 19"
}
```
The framework is built on top of these key dependencies (automatically included):
* **react-router** (v7) - Client-side routing
* **Tailwind CSS** (v4) - Styling framework
* **lucide-react** - Icon library
* **@tanstack/react-table** - Table component foundation
* **next-themes** - Dark mode support
* **sonner** - Toast notifications
## Tailwind CSS setup
AppShell uses Tailwind CSS v4 for styling. You need to import the AppShell theme in your global CSS file.
Import the AppShell theme before Tailwind:
```css app/globals.css theme={null}
@import "@tailor-platform/app-shell/theme.css";
@import "tailwindcss";
```
The import order matters! The AppShell theme must come **before** the Tailwind import to ensure proper CSS variable definitions.
```tsx Next.js (app/layout.tsx) theme={null}
import "./globals.css";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
```tsx Vite (src/main.tsx) theme={null}
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./globals.css";
ReactDOM.createRoot(document.getElementById("root")!).render(
);
```
### About the AppShell theme
The `theme.css` file includes:
* **Color palette** - Tailor's brand colors and semantic color tokens
* **CSS variables** - Design system tokens for spacing, typography, and more
* **Component styles** - Base styles for AppShell components
AppShell components use the `astw:` prefix for all Tailwind classes (e.g., `astw:bg-primary`) to avoid conflicts with your application's styles.
## Authentication setup
AppShell provides built-in OAuth2/OIDC authentication through the `AuthProvider` component.
You'll need three values from your Tailor Platform console:
1. **API Endpoint** - Your application's base URL
* Go to Application > Overview in Tailor Console
* Find "Accessing the API endpoint of this application"
* Use only the domain portion (e.g., `https://xyz.erp.dev`)
* Do **not** include the `/query` suffix
2. **Client ID** - Authentication client identifier
* Go to Application > Auth in Tailor Console
* Copy your Client ID
3. **Redirect URI** - OAuth2 callback URL (optional)
* Defaults to `window.location.origin` if not provided
* Must match the redirect URI configured in Tailor Auth settings
```tsx app/dashboard/page.tsx theme={null}
"use client";
import {
AuthProvider,
AppShell,
SidebarLayout,
} from "@tailor-platform/app-shell";
import { dashboardModule } from "../modules/dashboard";
const TAILOR_PLATFORM_URL = "https://xyz.erp.dev";
const CLIENT_ID = "your-client-id";
const App = () => (
(
Loading...
)}
>
);
export default App;
```
When `autoLogin` is `true`, unauthenticated users are automatically redirected to the login page. The `guardComponent` is shown while authentication state is loading.
Use the `useAuth` hook to access user information and auth methods:
```tsx components/UserProfile.tsx theme={null}
import { useAuth } from "@tailor-platform/app-shell";
export const UserProfile = () => {
const { authState, logout } = useAuth();
if (!authState.isAuthenticated) {
return null;
}
return (
);
};
```
### Supported identity providers
AppShell's `AuthProvider` works with any IdP configured in your Tailor Platform application:
* Tailor Platform built-in IdP
* Google Workspace
* Okta
* Auth0
* Microsoft Entra ID (Azure AD)
* Any OAuth2/OIDC-compliant provider
## Framework-specific setup
### Next.js (App Router)
AppShell works seamlessly with Next.js App Router using a catch-all route:
Create `app/dashboard/[[...props]]/page.tsx`:
```tsx app/dashboard/[[...props]]/page.tsx theme={null}
"use client";
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";
import { dashboardModule } from "../../modules/dashboard";
const Page = () => {
return (
);
};
export default Page;
```
Don't forget the `"use client";` directive! AppShell uses React hooks and client-side routing, so it must run on the client.
If you want `/` to redirect to `/dashboard`, create `app/page.tsx`:
```tsx app/page.tsx theme={null}
import { redirect } from "next/navigation";
const Page = () => {
redirect("/dashboard");
};
export default Page;
```
### Vite
AppShell works out of the box with Vite:
```tsx src/App.tsx theme={null}
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";
import { dashboardModule } from "./modules/dashboard";
const App = () => {
return (
);
};
export default App;
```
## Environment variables
For production deployments, store your Tailor Platform credentials in environment variables:
```bash .env.local (Next.js) theme={null}
NEXT_PUBLIC_TAILOR_PLATFORM_URL=https://xyz.erp.dev
NEXT_PUBLIC_CLIENT_ID=your-client-id
```
```bash .env (Vite) theme={null}
VITE_TAILOR_PLATFORM_URL=https://xyz.erp.dev
VITE_CLIENT_ID=your-client-id
```
Then use them in your code:
```tsx Next.js theme={null}
const TAILOR_PLATFORM_URL = process.env.NEXT_PUBLIC_TAILOR_PLATFORM_URL!;
const CLIENT_ID = process.env.NEXT_PUBLIC_CLIENT_ID!;
```
```tsx Vite theme={null}
const TAILOR_PLATFORM_URL = import.meta.env.VITE_TAILOR_PLATFORM_URL;
const CLIENT_ID = import.meta.env.VITE_CLIENT_ID;
```
Never commit credentials to version control. Add `.env.local` (Next.js) or `.env` (Vite) to your `.gitignore` file.
## Verification
To verify your installation is working:
1. Start your development server:
```bash theme={null}
npm run dev
```
2. Navigate to your base path (e.g., `http://localhost:3000/dashboard`)
3. You should see:
* Sidebar navigation with your modules
* Breadcrumb navigation
* Your module's component rendering
If you enabled authentication, you should be redirected to the login page first.
## Troubleshooting
### Styles not applying
Make sure you:
1. Imported `@tailor-platform/app-shell/theme.css` **before** `tailwindcss` in your global CSS
2. Imported your global CSS file in your app entry point
3. Restarted your development server after making CSS changes
### Authentication errors
Verify that:
1. Your API endpoint does **not** include `/query` (use only the domain)
2. Your Client ID matches exactly what's in Tailor Console
3. Your redirect URI is configured correctly in Tailor Auth settings
4. You're using HTTPS in production (required for OAuth2)
### TypeScript errors
Ensure your `tsconfig.json` includes:
```json theme={null}
{
"compilerOptions": {
"jsx": "react-jsx",
"moduleResolution": "bundler",
"esModuleInterop": true
}
}
```
## Next steps
Build your first AppShell application in 5 minutes
Learn how to structure your application with modules and resources
Deep dive into authentication, user types, and access control
Master client-side navigation and route guards