Skip to main content
This guide covers everything you need to install and configure AppShell in your React application.

​
Package installation

Install AppShell using your preferred package manager: 
npm install @tailor-platform/app-shell

​
Peer dependencies

AppShell requires React 19 or later as peer dependencies. Make sure you have them installed: 
npm install 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: 
"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.
1

Create or update your global CSS file

Import the AppShell theme before Tailwind:
app/globals.css
@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.
2

Import the global CSS in your app

import "./globals.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

​
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.
1

Get your Tailor Platform credentials

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
2

Wrap your app with AuthProvider

app/dashboard/page.tsx
"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 = () => (
  <AuthProvider
    apiEndpoint={TAILOR_PLATFORM_URL}
    clientId={CLIENT_ID}
    autoLogin={true}
    guardComponent={() => (
      <div style={{ padding: "2rem", textAlign: "center" }}>
        Loading...
      </div>
    )}
  >
    <AppShell
      title="My ERP App"
      basePath="dashboard"
      modules={[dashboardModule]}
    >
      <SidebarLayout />
    </AppShell>
  </AuthProvider>
);

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.
3

Access authentication state (optional)

Use the useAuth hook to access user information and auth methods:
components/UserProfile.tsx
import { useAuth } from "@tailor-platform/app-shell";

export const UserProfile = () => {
  const { authState, logout } = useAuth();
  
  if (!authState.isAuthenticated) {
    return null;
  }
  
  return (
    <div>
      <p>Welcome, {authState.user.name || authState.user.email}!</p>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
};

​
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:
1

Create a catch-all route

Create app/dashboard/[[...props]]/page.tsx:
app/dashboard/[[...props]]/page.tsx
"use client";
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";
import { dashboardModule } from "../../modules/dashboard";

const Page = () => {
  return (
    <AppShell
      title="My ERP App"
      basePath="dashboard"
      modules={[dashboardModule]}
    >
      <SidebarLayout />
    </AppShell>
  );
};

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.
2

Create a root redirect (optional)

If you want / to redirect to /dashboard, create app/page.tsx:
app/page.tsx
import { redirect } from "next/navigation";

const Page = () => {
  redirect("/dashboard");
};

export default Page;

​
Vite

AppShell works out of the box with Vite:
src/App.tsx
import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";
import { dashboardModule } from "./modules/dashboard";

const App = () => {
  return (
    <AppShell
      title="My ERP App"
      basePath="app"
      modules={[dashboardModule]}
    >
      <SidebarLayout />
    </AppShell>
  );
};

export default App;

​
Environment variables

For production deployments, store your Tailor Platform credentials in environment variables: 
NEXT_PUBLIC_TAILOR_PLATFORM_URL=https://xyz.erp.dev
NEXT_PUBLIC_CLIENT_ID=your-client-id
Then use them in your code: 
const TAILOR_PLATFORM_URL = process.env.NEXT_PUBLIC_TAILOR_PLATFORM_URL!;
const CLIENT_ID = process.env.NEXT_PUBLIC_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: 
    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:
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

​
Next steps

Quick start

Build your first AppShell application in 5 minutes

Module and resource definition

Learn how to structure your application with modules and resources

Authentication

Deep dive into authentication, user types, and access control

Routing and navigation

Master client-side navigation and route guards

Build docs developers (and LLMs) love

Get started for freeTalk to us