github.com/dev-family/admiral @v5.12.4

Revolutionize Your Workflow with Admiral: A Powerful Solution for Tailored Admin Panels and Business Applications

🌐 Try Live Demo  |  📖 Real-World Use Cases

Admiral is a frontend framework for creating back office in React. It provides out-of-the-box components and tools that make developing an admin interface easy and fast.

Made with :purple_heart: by dev.family

📖 Table of Contents

• ✨ Features
• 🚨 What problems do we solve
• 🔨 Installation
  • NPX
  • Use one of our examples
  • git clone
• 📦 Usage
  • 📦 Interaction with API
  • 📦 Menu
  • 📦 Hooks
  • 📦 Icons
  • 📦 Custom Theme
• 🗺️ Roadmap
• 📚 More Resources & Real-World Use Cases
• 🏆How can I support the developers?
• 🤝 Contributing
• © License
• 📚 Contact

✨ Features

• 📀 Out-of-the-box React components used.
• 🛡 It is written in TypeScript and has built-in typing.
• 👨‍💻 Adaptive design: The library interface scales to any screen size. This is convenient when used on mobile devices.
• 🌍 Localization: we support different languages.
• 👨‍🎨 An interface that is intuitively easy to work with.
• 🎨 Different design themes: you can change the color scheme of the interface to suit your needs.

🚨What problems do we solve

• Development complexity. Development complexity. We have collected ready-made components and tools to simplify and speed up development. Especially for those who are new to React.
• Inconsistent design. We created a unified design and style for all components so that you don't have any trouble generating new ones.
• Support complexity. We gathered all the necessary components and tools in one library, so that you don't waste your time looking for them.
• Low performance. We use modern technologies such as React Hooks, Redux, and GraphQL to achieve high performance and fast responsiveness of the interface. Your admin area will no longer be slowed down by the large number of requests to the server and complex operations on the client.
• CRUD. We have prepared tools to quickly create CRUD (Create, Read, Update, Delete) interfaces. Generate tables with data, forms for creating and editing objects, and components for deleting objects - in 5 minutes.

🔨 Installation

Requirements:

• The recommended Node.js versions are between 14.21.3 and 20.3.0. However, any version above 14.21.3 can be used. If any version incompatibilities are found, please create an issue describing the problem.

There are several options for installing Admiral:

📦 NPX

To use npx, make sure you have Node.js

npx create-admiral-app@latest

When you enter this command into the console, you will see 2 installation options:

• Install the template with backend on Express.js.
• Install the template without backend.

If you choose "Install the template with the backend setting on Express.js", you will install the fully customized template with backend on Express.js.

Detailed installation and startup instructions

All environment variables will be set automatically. If you want to configure them manually, go to the project folder and open the .env. You will have 1 CRUDs from the start - Users. To find them pass the way - admiral/src/crud/users/index.tsx

If you choose "Install the template without backend setting", you get just the frontend shell of Admiral in the admiral folder with CRUD - Users. To find it pass the way - admiral/src/crud/users/index.tsx. To use your backend, read the Documentation

Admiral is available at http://localhost:3000. If port 3000 is busy, any other free port will be selected.

In the console you will see something like this

Port 3000 is in use, trying another one...

vite v2.9.15 dev server running at:

> Local:    http://localhost:3001/
> Network:  http://192.168.100.82:3001/

ready in 459ms.

📦 Use one of our examples

Detailed installation and startup instructions are in each of the examples.

• Express Server

Open your browser and go to http://localhost:3000.

📦 Git Clone

Yes, that's right. You can just clone this repository and enter the following commands:

yarn
yarn dev

Then go to http://localhost:3000. The Admiral with mock data is now available to you.

📦 Usage

The App.tsx file is the entry point into the application. It is where the library is initialized and where the components are rendered Admin.

import React from 'react'
import { Admin, createRoutesFrom, OAuthProvidersEnum } from '../admiral'
import Menu from './config/menu'
import dataProvider from './dataProvider'
import authProvider from './authProvider'

const apiUrl = '/api'
// import all pages from pages folder and create routes
const Routes = createRoutesFrom(import.meta.globEager('../pages/**/*'))

function App() {
    return (
        <Admin
            dataProvider={dataProvider(apiUrl)}
            authProvider={authProvider(apiUrl)}
            menu={Menu}
            oauthProviders={[
                OAuthProvidersEnum.Google,
                OAuthProvidersEnum.Github,
                OAuthProvidersEnum.Jira,
            ]}
        >
            <Routes />
        </Admin>
    )
}

export default App

Interaction with API

Auth - AuthProvider

The main contract for authorization in the system is the interface AuthProvider.

export interface AuthProvider {
    login: (params: any) => Promise<any>
    logout: (params: any) => Promise<void | false | string>
    checkAuth: (params: any) => Promise<void>
    getIdentity: () => Promise<UserIdentity>
    oauthLogin?: (provider: OAuthProvidersEnum) => Promise<{ redirect: string }>
    oauthCallback?: (provider: OAuthProvidersEnum, data: string) => Promise<any>

    [key: string]: any
}

Example of implementation The interface itself can be customized to your liking, but it is important to respect the contract it provides. Detailed contract description

Let's look at the basic methods of implementation:

CRUD DataProvider

The main contract for working with data represents the interface DataProvider.

export interface DataProvider {
    getList: (
        resource: string,
        params: Partial<GetListParams>,
    ) => Promise<GetListResult<RecordType>>
    reorderList: (resource: string, params: ReorderParams) => Promise<void>
    getOne: (resource: string, params: GetOneParams) => Promise<GetOneResult<RecordType>>
    getCreateFormData: (resource: string) => Promise<GetFormDataResult<RecordType>>
    getFiltersFormData: (
        resource: string,
        urlState?: Record<string, any>,
    ) => Promise<GetFiltersFormDataResult>
    create: (resource: string, params: CreateParams) => Promise<CreateResult<RecordType>>
    getUpdateFormData: (
        resource: string,
        params: GetOneParams,
    ) => Promise<GetFormDataResult<RecordType>>
    update: (resource: string, params: UpdateParams) => Promise<UpdateResult<RecordType>>
    deleteOne: (resource: string, params: DeleteParams) => Promise<DeleteResult<RecordType>>

    [key: string]: any
}

Example of implementation Detailed contract description

Let's look at the basic methods of implementation: