Setup your project

Starting a new project

Start by creating a new folder (e.g. my-project) and extract the template-xpulse-v1.1.0.zip archive content into it.

# Create a new folder
mkdir my-project

# Extract the quickstarter archive
unzip template-xpulse-vv1.1.0.zip -d my-project

# Go to the newly created folder
cd my-project

Initialize a git repository

We recommend to initialize a new git repository for your project and create your first commit at this point.

# Create a new folder
git init

# Add all files to git
git add .

# Create your first commit
git commit -m "Initial commit"

WARNING

Remember to make your repository private if you fork or create a new git repository, as the template is a paid product.

Project overview

my-project/
├── public                  # Static files (images, favicon.ico, manifest.json, etc.)
├── src
│   ├── app                 # API routes
│   ├── components          # Reusable UI components
│   ├── context             # Shared state management (e.g., menu, layout, dashboard)
│   ├── data                # Sample data used in components and pages
│   ├── documentation       # Examples and samples used in documentation pages
│   ├── hooks               # Custom hooks and reusable logic/functions
│   ├── layouts             # Layout components for different sections of the site
│   ├── pages               # Route components (each file represents a route)
│   ├── styles              # CSS styles and font files
│   ├── types.ts            # Project-wide TypeScript types/interfaces
│   └── utils               # Utility functions and helpers (e.g., loading fonts, string manipulation)
├── next.config.js          # Next.js configuration settings
├── package.json            # Project dependencies and scripts
├── postcss.config.js       # PostCSS configuration for styles
├── prettier.config.js      # Prettier code formatting configuration
├── tailwind.config.js      # Tailwind CSS configuration
└── tsconfig.json           # TypeScript configuration settings

This is an overview of the most important files and folders in your project. Other files are for linters, testing, docker, etc.

Dependencies installation

Install the project dependencies by running the following command:

pnpm install

Start development mode

To start the development server, run one of the following commands:

pnpm dev

This will run the next dev script from the package.json file.

This should launch the development server:

• The dev:vite script will start the frontend (vite) server. Vite is the build tool that we use to compile the frontend code. It replaces webpack and vue-cli, used in earlier versions.
  Read more about it on vitejs.dev

TIP

• Access the Xpulse frontend in your browser at http://localhost:3000/

WARNING

If you have any trouble while installing, check the Common issues or contact us on our Support portal

Defining a project layout

Overview

Layouts are just components with a default slots. They are mostly used to wrap the nested routes. But they are a bit more complex than that as they are able to receive some props to adapt to the current page. There are 6 master layouts shipped with Xpulse. In the main demo, there is a layout switcher component that allows you to switch between them. But in your project, you will have to choose one and stick with it, like in any application.

You have to choose a layout from the available ones.

Xpulse layouts

Layout components are located src/components/layouts

Name	Identifier
Sidebar panel	sidebar-panel
Sidebar panel	sidebar-panel-float
Sidebar collapse	sidebar-collapse
Sideblock	sideblock
Sidedock	sidedock
Top navigation	top-navigation

The src/layouts project directory is the one that contains the active layout called inside your page. By default, it is the Default.tsx file. However, like we said before, this file contains a lot of Demo logic with all previously mentioned layouts to be able to switch between theme.

Notice that there is the Minimal.tsx which is basically an empty layout that you can use for specific pages, that differ from the regular ones, like authentication, wizards etc...

TIP

You may decide to build your own layout. In that case, Minimal.tsx would be a good starting point.

Enabling your selected layout

Like we said earlier, the Default.tsx layout file should not be used for production, because it is mostly made for demo purposes. If you look closer inside the same folder, there is a file named Default.sample.tsx, which will be the starting point for your project. You can rename it to Default.tsx after deleting the original Default.tsx file and start from there.

Let's take a look at this file:

import React, { FC } from 'react'
import Head from 'next/head'
import { useDashboardContext } from '@/context/DashboardContext'
import { useLayoutContext } from '@/context/LayoutContext'
import { layoutWrapperClasses, layoutNotPushedClasses, layoutPushedClasses } from '@/components/layouts/styles'
import SidebarPanelProvider from '@/components/layouts/sidebar-panel/SidebarPanelProvider'

type LayoutColors = 'default' | 'muted'

interface LayoutProps {
  children: React.ReactNode;
  title?: string;
  color?: LayoutColors;
  fullwidth?: boolean;
  horizontal?: boolean;
  nopush?: boolean;
}

const Layout: FC<LayoutProps> = ({ children, title, color = 'default', fullwidth = false, horizontal = false, nopush = false }) => {
  const { sidebarOpened } = useDashboardContext()

  const { activeLayout } = useLayoutContext()

  const wrapperClass = activeLayout.toLowerCase() + '-wrapper'

  return (
    <>
      <Head>
        <title>{title ?? 'Xpulse'}</title>
        <meta name="description" content="Multipurpose Next.js Admin and Webapp UI Kit" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="icon" href="/favicon.png" />

        <link rel="apple-touch-icon" href="/apple-icon.png" />
        <link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-precomposed.png" />
      </Head>
      <div className={`min-h-screen overflow-hidden transition-all duration-300 dark:bg-muted-900 ${color === 'muted' ? 'bg-muted-50' : 'bg-white'}`}>
        {activeLayout === 'sidebar-panel' && <SidebarPanelProvider fullwidth={fullwidth ? fullwidth : false} horizontal={horizontal ? horizontal : false} nopush={nopush ? nopush : false} />}

        <div
          className={`${wrapperClass} relative min-h-screen transition-all duration-300 dark:bg-muted-900 ${layoutWrapperClasses[activeLayout]} ${
            sidebarOpened && !nopush ? 'is-pushed ' + layoutPushedClasses[activeLayout] : layoutNotPushedClasses[activeLayout]
          } ${color === 'muted' ? 'bg-muted-50' : 'bg-white'}
            ${horizontal ? '!pb-0 !pe-0 !pt-0' : ''}
          `}
        >
          <div className={`${fullwidth ? 'max-w-full' : 'mx-auto max-w-7xl'} ${horizontal ? 'flex h-full min-h-screen flex-col [&>div]:h-full [&>div]:min-h-screen' : ''}`}>
            <div className={`${horizontal ? '' : 'pb-[100px] pt-4'}`}>{children}</div>
          </div>
        </div>
      </div>
    </>
  )
}

export default Layout

Looking at the file, we can see that the default selected layout is the SidebarPanelProvider which is the sidebar panel layout. You can change it to any other layout by replacing the SidebarPanelProvider component with the one you want to use namely:

• SidebarPanelProvider for the sidebar panel layout
• SidebarPanelFloatProvider for the sidebar panel float layout
• SidebarCollapseProvider for the sidebar collapse layout
• SideblockProvider for the sideblock layout
• SidedockProvider for the sidedock layout
• TopNavigationProvider for the top navigation layout

In this example, we'll assume that you've chosen the default layout, which is the sidebar panel layout. You don't have anything to change inside our Default.tsx file. Since you've chosen the sidebar panel layout, you don't need the other ones anymore. You can delete all the other folders inside the src/components/layouts folder, besides the src/components/layouts/sidebar-panel. If you were going to use the sidebar collapse layout, you would have to delete all the other folders inside the src/components/layouts folder, besides the src/components/layouts/sidebar-collapse folder and so on.

Follow up by updating the layout context file, located in src/context/LayoutContext.tsx. The file starts with an array containing the different layouts:

export const LAYOUTS = [
  "sidebar-panel",
  "sidebar-panel-float",
  "sidebar-collapse",
  "sideblock",
  "sidedock",
  "top-navigation",
] as const;

change it to:

export const LAYOUTS = [
  "sidebar-panel",
] as const;

If you were to choose the sidebar-collapse layout, you would have to change it to:

export const LAYOUTS = [
  "sidebar-collapse",
] as const;

Also, in the same file, make sure that the activeLayout variable is set to the layout you've chosen:

const useLayout = () => {
  const [activeLayout, setActiveLayout] = useState < LayoutType > 'sidebar-panel'
  //...
}

Understanding layout props

All layouts share common props that you can use to customize them. Here is a list of the props that you can use:

type LayoutColors = 'default' | 'muted'

interface LayoutProps {
  children: React.ReactNode;
  title?: string;
  color?: LayoutColors;
  fullwidth?: boolean;
  horizontal?: boolean;
  nopush?: boolean;
}

Let's take a look at each one of them:

• children: This is the content of the page that will be wrapped by the layout.
• title: This is the title of the page that will be displayed in the browser tab.
• color: This is the color of the layout. It can be either default or muted. The default color is white and the muted color is a light gray.
• fullwidth: This is a boolean that allows you to set the layout to full width.
• horizontal: This is a boolean that allows you to set the layout to horizontal, for horizontal scrolling pages like Kanban boards for instance.
• nopush: This is a boolean that allows you to disable the push effect of the layout (only relevant for sidebar-panel and sidebar-panel-float layouts.).

You should now have a fully functional layout for your project, and a basic understanding of the props that you can use to customize it.

Setup your IDE

VSCode and ES7+ React/Redux/React-Native snippets

The recommended IDE setup is VSCode with the ES7+ React/Redux/React-Native snippets extension. This extensions provides syntax highlighting and advanced IntelliSense for template expressions, component props and even slots validation. We strongly recommend this setup if you want to get the best possible experience with Xpulse.

React developer tools

If you are on a Chromium based browser, we recommend that you to install the React developer tools extension from any webstore: https://react.dev/learn/react-developer-tools