Documentation

This is a React - Nextjs frontend. In the following document you will find information about how to run the project template, how to deploy it and how to work with this template.
Getting Started
How to work with this template
If you are already familiarized with React and Nextjs, you can skip this section. If not, first you need to understand the main folder structure of this template, as it is important to know where each file is located.
  1. .next: This folder contains the build of the project. It is generated when you run the project.
  2. components: This folder contains the components of the project. Each created and used can be found here, along with its styles if necessary. In this case, this folder is missing, but it is useful in case one component is used in different pages and to keep modularity and avoid code duplicity.
  3. pages: This folder contains the pages of the project. Each page is a React component, and it is used to create the routes of the project. Some pages found in this folder are:
    • Index page, which is the main page of the project (in this case it is calling another page component, but it can also be included directly in this file.
    • _app page, which is the page that is shown in every route of the project, it is to say, the layout of the project. It is used to include components that will be present through each page, such as the topbar, menu and the footer of the project. In this case all this components are wrapped in a Layout component that will be explained later.
    • _document page is only rendered on the server side and not on the client side. This file is useful for meta tags, links to external stylesheets, etc. It is to say, it is useful to edit html structure and tags that are not related to React. Event handlers like onClick can't be added to this file because it is only rendered on the server side.
    • The 404 page, which is the page that is shown when a route is not found.

    4. From this basic files, the structure of the content can be created following a folder structure where the different pages can be found. In this case, the pages are divided in two folders: home and pages just as an example. The first one contains the dashboard content example and the static pages of the project (not found, error, access denied, login page), and the second one contains the mock pages with different components.

  4. layout: This folder contains the those components that define the layout of the project. In this case, it contains the topbar, the menu and the footer of the project. As it defines the structure of the project, it is the right place to configure context files and manage data between elements in the project.
  5. public: This folder contains the public files of the project which are static. The structure of the folder is made based on the function of the elements. In the /public/layout folder we can find all the aiprism logos (in different sizes and formats), as they will be used in the layout of the project. In the /public/images folder we can find the images that will be used in the content of the project (in previous versions, this was the public/static folder). In the /public/styles folder we can find the stylesheets that will be used in the project. In this case there are two stylesheets based on the colors of the project, one for dark mode and other for light mode.
  6. styles: This folder contains the global styles of the project that will affect the project. In the /styles/demo folder there are some css for specific components as an example. The /styles/layout folder contains the styles for the layout components (topbar, menu and footer), and other aspects which will affect the layout of the project in general. It would be in this folder where the stylesheets for the different pages of the project could be included, but they could also be included in the components or pages folder.
How to run the project
Environment variables
Environment variables are dynamic values that are set outside of an application and are used to configure or control the behaviour of some aspects of the application. They can refer to keys or passwords to access certain services or databases, or to urls of external services. For example, the environment variables can be used to store the url of the backend service, which will be used to make the requests. In NextJS, they can be applied in two ways:
  • Loading Environment Variables. In this case, the environment variables are loaded in the /next.config.js file, and compiled in the server side. This means that they can only be accessed through the server side code, but not from the client, keeping them secured. To be able to access them from the browser the variable needs no be defined as PUBLIC.
    • They can be included in the project through two systems. In the /next.config.js file:
    const nextConfig = {
       env:{
           EXAMPLE: "12345"
       }
    }
    They can also be defined in an .env file:
    EXAMPLE=152452
    They can be easily accessed in the project through the process.env object and would return the content:
    const example_value = {process.env.EXAMPLE}
    So example_value now is: 152452
  • Bundling Environment Variables for the Browser. Here variables are included directly in the code sent to the browser when compiled. This means that they can be accessed from the client side code.
    • const nextConfig = {
       publicRuntimeConfig:{
           EXAMPLE: "123456"
       }
    }
    They can be easily accessed in the project through the process.publicRuntimeConfig object and would return the content:
    import getConfig from "next/config"
    const { publicRuntimeConfig } = getConfig() 
    ...
    const example_value = { publicRuntimeConfig.EXAMPLE}
    So example_value now is: 123456

    They can also be defined in an .env file but specifying it as a public variable adding NEXT_PUBLIC_ at the beginning of the variable name
    import getConfig from "next/config"
    const { publicRuntimeConfig } = getConfig() 
    ...
    NEXT_PUBLIC_EXAMPLE=123456
    They can be easily accessed in the project through the process.env object and would return the content:
    const example_value = { publicRuntimeConfig.NEXT_PUBLIC_EXAMPLE}
    So example_value now is: 123456
Development
While developing the project, you can run the project in development mode. To do so, you need to run the following command:
   npm run dev
All changes made in the code will be automatically updated in the browser, which will be opened in the following url:
   http://localhost:3000
Production
To run the project in production mode, you need to run the following command:
   npm run build
and then
   npm run start
The first command will generate the build of the project, and the second one will run the project in production mode. The browser will be opened in the following url:
   http://localhost:3000
Dockerfile
A Dockerfile is included in the project template frontend to build a docker image. To build the image, you need to run the following command:
   docker build -t aiprism:0.1 .
Where aiprism is the name of the image and 0.1 is the tag of the image. Then, to run the image, you need to run the following command:
   docker run -p 80:3000 aiprism:0.1
Where we indicate the name of the image, that needs to be the same used to build it (In this case aiprism). The same happens with the tag of the image. The -p flag is used to indicate the port that will be used to run the image. In this case, the port 80 will be used.
Copyright © CIGIP 2024.