Project Architecture

Steroids provides a unified architecture for your projects. By following these principles and rules, you will be able to quickly create complex applications that will be easy to maintain in the future.

Application Structure

The general structure of an application with a single page and layout looks as follows:

├── node_modules
1├── public - build directory used by the web server
2├── src
3│   ├── actions - redux actions
4│   ├── reducers - redux reducers
5│   ├── modals - modal windows
6│   ├── routes - application routes (pages)
7│   │   └── IndexPage - react component folder
8│   │       └── views - components used only in IndexPage
9│   │           ├── MyBox.ts
10│   │           └── MyBox.scss
11│   │       ├── IndexPage.ts - react component
12│   │       ├── IndexPage.scss - BEM styles for the component
13│   │       └── index.ts - component loading as a directory
14│   ├── shared - shared components
15│   │   └── Layout
16│   │       ├── Layout.ts
17│   │       ├── Layout.scss
18│   │       └── index.ts
19│   ├── ui - styled and custom UI components
20│   │   └── form
21│   │       ├── Button
22│   │       │   ├── ButtonView.tsx
23│   │       │   └── ButtonView.scss
24│   │       └── CustomField
25│   │           ├── CustomField.ts
26│   │           ├── CustomFieldView.tsx
27│   │           └── CustomFieldView.scss
28│   ├── style
29│   │   ├── index.scss - main style file
30│   │   └── variables.scss - SCSS variables
31│   ├── Application.tsx - main application component
32│   └── index.tsx
33├── .eslintrc
34├── index.d.ts - global definition of types for code written without typescript
35├── package.json
36├── tsconfig.json
37├── webpack.js
38└── yarn.lock

You can add static assets (images, fonts) to the public directory for their use in the application via absolute paths. This directory will also store minified application bundles generated by Webpack.

The src directory contains the project's source code, which is not published when deploying the project to production.

At the root of the sources, there are two files - index.tsx and Application.tsx. It's recommended to keep their separation and names exactly as they are, as when using SSR (Server-Side Rendering), the Node.js server application will render Application.tsx. The index.tsx file is used solely for rendering through react-dom in the browser.

The actions and reducers directories contain actions and reducers for the redux store, respectively. They don't need to be created if the library already provides many reducers that the application can use. If the reducers directory is not created, Webpack will use reducers from the library node_modules/@steroidsjs/reducers.

All routes are defined in the routes/index.ts file. You can read more about their capabilities and format in the Routing.

React components of the application are distributed according to the foldersmodals, routes,shared and ui. They should not be declared in other folders to maintain the structure and ease of navigation.

Application Customization

In the Application.tsx file, you can customize the application by adding custom reducers, components, and icons. Here is how the file looks in the boilerplate:

import useApplication from '@steroidsjs/core/hooks/useApplication';
1import HttpComponent from '@steroidsjs/core/components/HttpComponent';
2import LocaleComponent from '@steroidsjs/core/components/LocaleComponent';
3import customIcons from 'icons/index';
4
5import 'style/index.scss';
6
7export default function Application() {
8    const {renderApplication} = useApplication({
9        reducers: require('@steroidsjs/core/reducers').default,
10        routes: () => require('routes').default,
11        layoutView: () => require('shared/Layout').default,
12        screen: {},
13        components: {
14            locale: LocaleComponent,
15            http: HttpComponent,
16        },
17        onInit: ({ui}) => {
18            ui.addViews(require('./ui/bootstrap').default);
19            ui.addFields(require('@steroidsjs/core/ui/form').default);
20            ui.addFormatters(require('@steroidsjs/core/ui/format').default);
21            ui.addIcons(require('@steroidsjs/bootstrap/icons/index').default(customIcons));
22        },
23    });
24
25    return renderApplication();
26}

Detailed instructions on customizing various parts of the application can be found in the article Application Customization.

React Components

React components in the Steroids framework have some distinctive features and advantages:

Separate core and view parts for each component.
The ability to customize styles through SCSS variables.
Full replacement capability for both *.scss and *.tsx component files for customization.
The option to add custom components.
TypeScript interfaces described for components and their view parts.
Global configuration (default props) for all components or selected ones.
Logic of UI components working in conjunction with application components, routing, and Redux.
The possibility of processing metadata models and enums coming from the backend to create forms based on them.

Separation of Logic and Presentation in a Component

Each UI component (form element, list, modal window, etc.) consists of two parts:

1. Core: The core of the component contains all the business logic. It receives and processes data from props, finds the appropriate view of the component, and passes the prepared data to it. The core component does not contain jsx code and does not interact with DOM elements.

2. View: The view is responsible for the direct rendering of the component. It includes only jsx code and scss styles for the component with minimal or no business logic. When customizing the component, its *View.tsx and/or *View.scss files can be fully copied into the project and modified to fit the design of a specific project.

For more details on how to take advantage of the separation of core and view parts of a component, you can read here.

File Structure of a Component

React components consist of two files - tsx and scss. Even if there is no immediate need to style a component, but it contains jsx code, it is still recommended to create a *.scss style file and import it via import in the *.tsx file. This ensures a consistent file structure for all components in the project.

Each component is placed in a separate folder with an index.ts file. This file contains the import and export of the component:

import IndexPage from './IndexPage';
1export default IndexPage;

The index.ts file is used to export the component from the folder. With these files for components, the project code can use concise imports, for example, routes/IndexPage instead of lengthy imports from the component file, such as routes/IndexPage/IndexPage.

For larger components, such as application pages, nested components are extracted. If such components are only used in a specific component, they should be placed in the views folder (see routes/IndexPage/views/* in the structure). If components are reused in other large components, such as on other application pages, they should be moved to the top level in the shared folder (see src/shared in the structure).

Common Styles

The base styles of the application are located in the src/style folder and are exported from the src/style/index.scss file. They are imported during the initialization of the application in the Application.tsx file.

Common styles are used to declare the fonts used, basic styles for HTML tags, mixins, and SCSS variables. Additionally, in this file, CSS files from various libraries or default styles for Steroids can be included, for example: @import '@steroidsjs/bootstrap/index.scss';

SCSS variables that will be used in various components are imported into a separate file - style/variables.scss. Its further usage in components looks like this:

@use "style/variables";
1
2.Block {
3  background-color: variables.$gray;
4  border: 1px solid variables.$graphite;
5}

If you have a large number of variables that can be grouped, the file structure would look like the following:

├── style
1│   ├── variables - папка с файлами для scss-переменных
2│   │   ├── colors.scss - scss-переменные для цветов
3│   │   ├── typography.scss - scss-переменных для типографики
4│   │   └── index.scss - экспорт всех файлов с scss-переменными из папки
5│   ├── index.scss - главный файл стилей
6│   └── variables.scss - содержит импорт index файла из папки variables и другие файлы с переменными (например для библиотек)

SCSS mixins are imported into a separate file - style/mixins.scss. Their further usage in components looks like this:

@use "style/mixins";
1
2.Block {
3  @include mixins.loading(1s);
4}

If scss-mixins can be divided into groups, with each group in a separate file, the structure will be the same as for scss-variables.