React-TS Project template

by Phenomenon.Studio

This project was bootstrapped with Vite.js.

Table of contents:

React-TS Project template

📦 Stack

React.js - UI library
Typescript - Static type checker
Vite - Bundler
Tanstack Query - Asynchronous state management
Tanstack Router - Routing (file-based)
Axios - HTTP client
Zod - Schema validation
React Hook Form - Form management
@svg-use - icon management tool
Eslint - Code linter
Prettier - Code formatter
Husky - commands execution handler on git events

🚀 Quick start

Install Node.js;

Require Node.js version >=22.0.0
Install the NPM dependencies by running npm ci;
Create .env.local then add variables. You can look at the .env.local.example file;

🤖 Commands

Runs the local dev server at localhost:3000:
```
npm run dev:vite
```
Runs tsc CLI in watch mode:
```
npm run dev:tsc
```
Runs the local dev server and tsc together:
```
npm run dev
```
Builds your production site to ./dist/:
```
npm run build
```
Previews your build locally, before deploying at localhost:4173:
```
npm run preview
```
Checks your JavaScript/TypeScript for errors and warnings:
```
npm run lint:eslint
```
Checks your CSS for errors and warnings:
```
npm run lint:stylelint
```
Checks your code formatting:
```
npm run lint:prettier
```
Checks your code all together:
```
npm run lint
```
Fixes your code formatting:
```
npm run fix:prettier
```
Installs husky:
```
npm run prepare
```

🧶 Structure

API requests

API requests are created globally in the root of the project to be used inside API hooks. API request are not directly called in project, only in hooks.

API requests should be located inside src/api folder.

API requests are performed with some library like ky, axios etc. Based on the library, src/api folder should contain the appropriate file @ky.ts or @axios.ts. This file should contain all instances for all origins.

Example:

// @axios.ts

export const http = axios.create(...);
export const httpPrivate = axios.create(...);

API requests should:

be separated to files based on its scope.
- Example: users requests -> users.ts; forms requests -> forms.ts

API queryClient options

When Tanstack Query is used, queryClient entity is created once on project start, and is used within all the application. By setting it in global api folder, we will be able to use it wherever needed in the app.

The query client configuration file should be located at src/tanstackQuery/@queryClient.ts and include configuration as follows as bare minimum:

import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
    defaultOptions: {
        queries: {
            refetchOnWindowFocus: false,
            retry: 1,
        },
        mutations: {
            retry: 1,
        },
    },
});

This configuration should be passed to <QueryClientProvider /> in src/main.tsx file.

NOTE: This configuration as allowed to be used wherever using useQueryClient hook is not allowed:

routes loaders

functions may include api logic (setting query data etc.)

Icons

Icons should be located at src/icons folder.

Every icon should:

Have lowercase name with kebab case formatting (example: profile.svg or airplane-landing.svg)

Prerequisites:

Compress exported SVG with SVGOMG tool

Contexts

Contexts are optional for the root of the project and components among all the project.

No matter, where the contexts will appear, they should:

Have separate contexts folder inside the folder where the hooks will be used
- Global contexts will be used in all the project, should be located at src/contexts folder. NOTE: Any component is allowed to call such contexts.
- If context will be used inside single component exclusively, you should create contexts folder inside the component folder. Example: src/components/ArticleCard/contexts. NOTE: such contexts are not allowed to be used outside of the component scope where the hooks folder were created. If such case appears, then you should move the hook(s) into global hooks folder. The child components (src/components/ArticleCard/components/*) only are allowed to use the context inside

Each context should:

Be created inside the contexts folder
Have pascal case name, ending with <contextName>Context (example: AuthContext.tsx)
NOTE: The context file name should match the context name inside the file

// src/contexts/AuthContext.tsx

const AuthContext = createContext(...);

Stores

Stores are optional for the root of the project. Current rules are applied for zustand stores

Stores are allowed to use in all the project.

Stores should:

Have separate root src/stores folder

Each store should:

Have camel case name, ending with <storeName>Store (example: authStore.tsx)
NOTE: The store file name should match the store hook name name inside the file
- <storeName>Store.ts -> use<StoreName>Store.ts

// src/stores/authStore.ts

export const useAuthStore = create(...)

Hooks

Hooks are optional for the root of the project and components among all the project.

No matter, where the hooks will appear, they should:

Have separate hooks folder inside the folder where the hooks will be used
- Global hooks will be used in all the project, should be located at src/hooks folder
- If hook will be used inside single component exclusively, you should create hooks folder inside the component folder. Example: src/components/ArticleCard/hooks. NOTE: such hooks are not allowed to be used outside of the component scope where the hooks folder were created. If such case appears, then you should move the hook(s) into global hooks folder

Each hook should:

Be created inside the hooks folder
Have camel case name, starting with use (example: useHavePermissions.ts)
NOTE: The hook file name should match the hook name inside the file

// src/hooks/useHavePermissions.ts

export const useHavePermissions = () => {...}

API hooks

Because of using Tanstack query, and its hooks mechanic, following the TkDodo's recommendations, all API requests should be inside custom hooks that call useQuery and useMutation hooks. API requests were described in the relevant section above.

API hooks should be located inside src/tanstackQuery folder.

API hooks should:

be named for the api file. src/api/users.ts -> src/tanstackQuery/users.ts
contain all hooks for every function declared in the api requests file

Single API hook should:

be named for the api request function. <requestName> -> use<RequestName>
- Example: submitForm -> useSubmitForm

Query hooks

Query hooks can have the parameters to be passed like pagination, search params etc. These parameters should be passed into hooks as arguments. Recommended to pass the arguments as list of arguments, not as the object.

Query keys should be defined as described in Query keys section.

Example:

export const useGetBooks = (search: string) => {
    return useQuery({
        queryKey: BOOKS_QUERY_KEYS.listWithParams({ search })
        // ...
    })
}

export const useGetBooksByAuthorName = (authorName: string, search: string) => {
    return useQuery({
        queryKey: BOOKS_QUERY_KEYS.itemByAuthor(authorName, { search })
        // ...
    })
}

Query Keys

It is also recommended to manage query keys in appropriate way to use them inside project.

First things first, you should create the constant that includes queryKeys:

// src/tanstackQuery/books.ts

export const BOOKS_QUERY_KEYS = {
    all: ['books'] as const,
    list() {
        return [...BOOKS_QUERY_KEYS.all, 'list'] as const
    },
    listWithParams(params: { search: string }) {
        return [...BOOKS_QUERY_KEYS.list(), params] as const
    }
    // ...
}

NOTE: Query keys contacts are allowed to be used in all the project to make invalidations and prefetched possible on a lot of events occur by user activities.

And apply this in:

Query hooks:

export const useGetBooks = (search: string) => {
  return useQuery({
      queryKey: BOOKS_QUERY_KEYS.listWithParams({ search })
      // ...
  })
}

Query options:

export const getBooksQueryOptions = (search: string) => {
  return queryOption({
      queryKey: BOOKS_QUERY_KEYS.listWithParams({ search })
      // ...
  });
}

export const useGetBooks = (search: string) => {
  return getBooksQueryOptions(search);
}

Query invalidations:

import { BOOKS_QUERY_KEYS } from '@/tanstackQuery/books';

queryClient.invalidateQueries({
  queryKey: BOOKS_QUERY_KEYS.list()
})

Query prefetches:

import { BOOKS_QUERY_KEYS } from '@/tanstackQuery/books';

queryClient.prefetchQuery({
   queryKey: BOOKS_QUERY_KEYS.list()
})

// or

queryClient.getQueryData({
   queryKey: BOOKS_QUERY_KEYS.list()
})

Mutation hooks

Mutation hooks from useMutation return the callable function as result, so no need to pass the arguments into hook call. But everything can happen to pass initial arguments into hook body directly for query client logic or whatever.

// src/tanstackQuery/books.ts

export const addBookToFavorites = (bookId: string) => {...}

// src/tanstackQuery/books.ts

import { addBookToFavorites } from '@/tanstackQuery/books';

export const useAddBookToFavorites = () => {
    return useMutation({
        mutationFn: addBookToFavorites
        // ...
    })
}

// somewhere
import { useAddBookToFavorites } from '@/tanstackQuery/books';

// ...

const { mutate: addBookToFavorites } = useAddBookToFavorites();

// ...

addBookToFavorites(bookId, {...})

Utility functions

Utility functions are optional for the root of the project and components among all the project.

No matter, where the utils will appear, they should:

Have separate utils folder inside the folder where the utils will be used
- Global utils will be used in all the project, should be located at src/utils folder
- If util will be used inside single component exclusively, you should create utils folder inside the component folder. Example: src/components/ArticleCard/utils. NOTE: such utils are not allowed to be used outside of the component scope where the utils folder were created. If such case appears, then you should move the util(s) into global utils folder

Each util should:

Be created inside the utils folder
Have camel case name (example: getHasPermissions.ts)
NOTE: The util file name should match the util name inside the file
(Optional): Unit tests can be written for the util
- <utilName>.ts -> <utilName>.test.ts

//getHasPermissions.ts

export const getHasPermissions = () => {...}

Constants

Constants are optional for the root of the project and components among all the project.

There are 2 types of constants to use:

Regular constants (constants.ts)
Schemas constants (schemas/ folder)

The rules described below are applied for both of them. The only difference is:

constants.ts - for regular constants like time tokens, regexps etc.
schemas/ folder - for zod schemas will be used in other schemas in all the project

No matter, where the constants will appear, they should:

Have separate constants.ts file inside the folder where the constants will be created
- Global constants will be used in all the project, should be located at src/constants.ts file
- If constants will be used inside single component exclusively, you should create constants.ts file inside the component folder. Example: src/components/ArticleCard/constants.ts.
NOTE: such constants are not allowed to be used outside of the component scope where the constants file were created. If such case appears, then you should move the constants(s) into global constants file

Schemas

Schemas should:

Have separate schemas folder inside the folder where the schemas will be used
- Global schemas will be used in all the project, should be located at src/schemas/ folder
- If schemas will be used inside single component exclusively, you should create schemas/ folder inside the component folder. Example: src/components/ArticleCard/schemas/.
Each schema should have camel case name with ending <schemaName>Schema.ts.
Each schema should have its inferred type

Few more thing should be applied to schemas:

import { z } from 'zod';
// ...

export const signUpSchema = z.object({...});
export type SignUpSchema = z.infer<typeof signUpSchema>;

Types

Types are optional for the root of the project and components among all the project.

The root project types should include:

Generic global types
Global primitive types for several components

The components types should include:

Component props
Components props partitions

Styles

Styles are optional for the root of the project and components among all the project.

The global styles are located inside src/styles folder This folder should include:

index.css - root project styles (incl. imports of other root style files described below)
reset.css - predefined browsers styles reset file
variables.css - (optional) global variables file. This file can be created if there are a lot of variables to create and manage them easily. In case of ~25 variables they can still be maintained in index.css.
fonts.css - (optional) global fonts to be implemented through @font-face directive.

Components

Components should be located at:

src/ui
- basic primitive components (Example: buttons, typography, wrappers etc.)
- do not have complex logic (complex hooks, contexts)
- can NOT use src/components components inside
src/components
- complex components use src/ui components inside as building blocks
- Can have any types of hooks, contexts inside

Anatomy

The component should:

Have separate folder
Have pascal case name (example: Button or ArticleCard)
Have default export of the component itself

The component folder should contain:

index.tsx - the component JSX, entry points of component
styles.module.css - the styles of component file (optional)

NOTE: If component has to haves hooks/utils/constants/contexts, take a look at relevant chapters above.

Modules

Modules are core blocks are used for routing. Router entries render modules only. It is not allowed to pass the components from src/components or src/ui.

Modules are located at src/modules folder.

Modules represent pages we should display within router. Modules hierarchy may also represent the routes subrouting.

Every module should:

be named for the route it represent:
- http://localhost:3000/about -> src/modules/About
have the same architecture as src/components or src/ui as described above
have no props

module name should match the module component name:

// src/modules/About/index.tsx

export const About: React.FC = () => {...}

Modules are allowed:

to use src/components and/or src/ui components inside
to have own hooks
to have own constants/schemas/styles
to have own sub-modules and/or sub-components (src/modules/About/components/...)
to use its sub-modules inside if it is not a sub-route

Submodules

Submodules are the modules inside the some module (src/modules/About/components/...).

Submodules may have everything regular modules can have and do, but they can be used in two ways:

as sub-component for the rot module
- but it is already not allowed to be used as sub-route
as sub-route:
- src/modules/About/components/Settings -> http://localhost:3000/about/settings

Routing

Tanstack Router is used as main router utility with file-based routing functionality.

Routes are located at src/routes folder.

`__root.tsx` file

Thi file is used to set up the initial router with global component and parameters.

Root file may include:

Devtools
Global context providers
404 page set up

File-based routing

All files and folders inside src/routes folder are represented as client routes by the file name:

src/routes/index.tsx -> http://localhost:3000/
src/routes/about.tsx -> http://localhost:3000/about

Folders cam include the subroutes and index route:

src/routes/about/index.tsx -> http://localhost:3000/about
src/routes/about/settings/index.tsx -> http://localhost:3000/about/settings

Routes can be lazy-loaded or not.

Lazy-loaded routes can:

render the module dynamically when the route is called
include pending components
include error component
include 404 component

Regular route can:

everything lazy-loaded routes can
validate search parameters
perform prefetches with loader
perform actions before loader executes

NOTE: regular routes have more memory load, so if no need in search parameters load or prefetch, plea use lazy routes.

Route have different file naming convection inside src/routes folder:

Routes should:

be named with kebab-case lowercase (src/routes/<route-name>/)
have index file with .tsx extension (src/routes/<route-name>/index.tsx)
If lazy - add .lazy before .tsx (src/routes/<route-name>/index.lazy.tsx)
have no props

have route module name matched to route name but pascal-case ending with <ModuleName>Page:

// src/routes/about/index.tsx

import About from '@/modules/about';

const AboutPage = createLazyFileRoute('/about')({
  component: About
})

Mixing route types

There is possibility to have route mixing between lazy and regular.

We are able to split the logic this way:

Regular route
- validate search parameters
- perform prefetches with loader
- perform actions before loader executes
Lazy route
- render the module dynamically when the route is called

In terms of code it looks this way:

Folder structure:

src/
└── routes/
    └── about/
        ├── index.tsx
        └── index.lazy.tsx

// index.lazy.tsx

import About from '@/modules/about';

const AboutPage = createLazyFileRoute('/about')({
    component: About
})

// index.tsx
import { noopReturnNull } from '@/utils/noopReturnNull';

const AboutPage = createFileRoute('/about')({
    component: noopReturnNull,
    validateSearch(search) {...},
    beforeLoad() {...}
    loader({ search }) {...},
})

Layouts

Tanstack router allows to create layouts.

Layouts should:

be named for layout semantics, kebab-case, starting with _ and ending with -layout:
- Example: src/routes/_protected-layout/

have both folder and file (not lazy) named by this layout:

src/
  └── routes/
      ├── _protected-layout/
      │   └── index.lazy.tsx
      └── _protected-layout.tsx

Layout component should be stored at src/components/layouts folder.

Layout components should:

have same structure as src/components have
include <Outlet /> a child of component
have no props

// src/components/layouts/ProtectedLayout/index.tsx
import { Outlet } from '@tanstack/react-router';

const ProtectedLayout: React.FC = () => {
    return (
        <div>
            // ...
            <Outlet />
        </div>
    )
}

// src/routes/_protected-layout.tsx

import ProtectedLayout from '@/components/layouts/ProtectedLayout';

const ProtectedLayoutPage = createFileRoute('/_protected-layout')({
    component: ProtectedLayout
    // ...
})

Route API hooks

Routes have own hooks like useSearch and useNavigate or other that getRouteApi return (docs). For optimizing the router tree iterations and by following the maintainer recommendations we should have the from attribute predefined for each route we have the hooks calls at.

it is recommended to create custom route hooks for each module as follows:

be located in module hooks folder
have name based on module name: src/modules/<ModuleName>/ -> src/modules/<ModuleName>/hooks/use<ModuleName>RouteApi.ts:
- Example: src/modules/About/ -> src/modules/About/hooks/useAboutRouteApi.ts

// src/modules/About/hooks/ueAboutRouteApi.ts

import { getRouteApi } from '@tanstack/react-router';

const aboutRouteApi = getRouteApi('/about');

export const ueAboutRouteApi = () => {
    const search = aboutRouteApi.useSearch();
    const navigate =  aboutRouteApi.useNavigate();

    return { search, navigate };
}

// src/modules/About/index.tsx

const About: React.FC = () => {
    const { search, navigate } = ueAboutRouteApi();

    // ...
}

If no search needed, you may just return the navigate. Route API logic allows us to get the route data directly by setting the entry point as route id, which is autocompleted in dev mode launched.

This methodology can be applied to layouts a well.

✳️ Icons Usage

Collect all icons as separate files with .svg extension and kebab-case naming.

Example:

src
├── icons
│   ├── arrow-left.svg
│   ├── search.svg
│   └── arrow-right-circle.svg

Import icon required as follows:

import { Component as ArrowLeftIcon } from '@/icons/arrow-left.svg?svgUse';

Use the icon as regular JSX component:

<ArrowLeftIcon className={s.icon} />

Type of the component and its props: Location: Location: node_modules/@svg-use/react/dist/esm/ThemesExternalSvg.d.ts

declare const createThemedExternalSvg: ({ url, id, viewBox }: FactoryProps) => (props: ThemeProps & SVGAttributes<SVGSVGElement>) => JSX.Element;

export interface ThemeProps {
	color?: string;
	colorSecondary?: string;
	colorTertiary?: string;
}

Key moments:

👉 Import Component names export, then name it as applicable icon naming is.
👉 Autocomplete will support path to the svg file, ⚠️BUT⚠️ you should add ?svgUse param at the end of import statement for @svg-use to work

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

React-TS Project template

📦 Stack

🚀 Quick start

🤖 Commands

🧶 Structure

API requests

API queryClient options

Icons

Contexts

Stores

Hooks

API hooks

Query hooks

Query Keys

Mutation hooks

Utility functions

Constants

Schemas

Types

Styles

Components

Anatomy

Modules

Submodules

Routing

`__root.tsx` file

File-based routing

Mixing route types

Layouts

Route API hooks

✳️ Icons Usage

Files

README.md

Latest commit

History

README.md

File metadata and controls

React-TS Project template

📦 Stack

🚀 Quick start

🤖 Commands

🧶 Structure

API requests

API queryClient options

Icons

Contexts

Stores

Hooks

API hooks

Query hooks

Query Keys

Mutation hooks

Utility functions

Constants

Schemas

Types

Styles

Components

Anatomy

Modules

Submodules

Routing

__root.tsx file

File-based routing

Mixing route types

Layouts

Route API hooks

✳️ Icons Usage

`__root.tsx` file