# Getting Started

{% hint style="info" %}
This is the documentation for **"SPIN" v2:** [v2.react.spin.webkom.co](http://v2.react.spin.webkom.co)
{% endhint %}

## Intro

After placing the extracted files in a directory on your local system, you should execute `npm install` in the root of the project. **Attention!** - Please be sure the `.npmrc` file is present in the root of the directory. On Unix based systems, files which start with a dot are hidden by default, which sometimes can cause confusion.

## Commands

`npm start` - start the development version with hot reloading enabled

`npm start:prod` - start the production version with SSR enabled

`npm build:client` - build the client application only (no SSR)

`npm build:prod` - build the application with SSR; this package should then be launched with `node` on the server

## Project Structure

`app/components/*` - Place general React components here, reference them in the `index.js` file so they can be imported easilly later in the project.

`app/layout/*` - The main `<Layout>` component should be defined in the `default.js` file. Layout components such as **Sidebars**, **Navbars** should be placed in the `./components` subdirectory.

`app/routes/*` - Route components should be defined in here. They should be attached to the Router via 3 functions which are placed at the bottom of the file. This will be described in a more detailed way in further sections.

`app/styles` - Non-modular SCSS should be placed here. There are already 4 files here - `bootstrap.scss`, `main.scss`, `variables.scss`, `_font-awesome.scss`. Those files import Bootstrap4 and all of the modifications for the dashboard layout, aswell as FontAwesome as a plugin.

`app/colors.js` - You can import this file to use the colors defined in the dashboard style.

`app/index.html` - The main html file which initializes the application.

`app/server/*` - Setup of the Express server which supports SSR in the application.

`build/*` - WebPack configuration files and other build tools.

`dist/` - Production build files will be genereated here.

## Adding Routes

1. Create a directory for the route (let's call it ExampleRoute) in `app/routes/ExampleRoute`.
2. Add 2 files `ExampleRoute.js` and `index.js`.
3. Inside of the `ExampleRoute.js` add the definition of the component. For example:

   \`\`\`jsx

   import React from 'react';

export const ExampleRoute = () => ( Hello World );

````
4. Re-export the component from `index.js` like so:
```jsx
import { ExampleRoute} from './ExampleRoute';

// NOTE: The component should be exported as a `default` here.
export default ExampleRoute;
````

1. Now you need to attach the route to ReactRouter:
2. If you need the route to be *static* which means that it will be loaded at the start of the application just import the route and add it to the body of `getRoutes` function like so:

   ```jsx
   /// (...)
   import ExampleRoute from './ExampleRoute`;
   /// (...)
   const getRoutes = () => {
     return (
         <Switch>
             { /* (...) */ }
             <Route path="/example-route">
                 <ExampleRoute/>
             </Route>
             { /* (...) */ }
         </Switch>
     );
   }
   ```
3. You can also make the route asynchronous, then it will be loaded only when the user navigates to it. This technique reduces the initial load time, as the browser doesn't need to load the whole application on start. You can add an async route as follows:

   ```jsx
   /// (...)
   import { UniversalComponent } from './universalComponent';
   /// (...)
   const getRoutes = () => {
     return (
         <Switch>
             { /* (...) */ }
             <Route path="/example-route">
                 { /* page prop defines which subdirectory should be asynchronously loaded */ }
                 <UniversalComponent page="ExampleRoute"/>
             </Route>
             { /* (...) */ }
         </Switch>
     );
   }
   ```
4. Last step is to add the Sidebar entry. Open the `app/layout/components/SidebarMiddleNav.js` file where all sidebar route entries should be added. Example:

   ```jsx
   export const SidebarMiddleNav = () => (
    <SidebarMenu>
        { /* (...) */ }
        <SidebarMenu.Item
            icon={<i className="fa fa-fw fa-home"></i>}
            title="Example Route"
            to='/example-route'
        />
        { /* (...) */ }
    </SidebarMenu>
   );
   ```
5. Now you should be able to navigate to the newly created route through the sidebar.

## Layout

You can change the general layout, as well as add specific Navbars and Sidebars for different routes.

### General Layout structure

Whole page layout is composed of the `<Layout>` component and its subcomponents. This composition should be placed in `app/layout/default.js` In more details the usage of this component [is described here.](https://github.com/0wczar/react-dashboards/wiki/Bootstrap4-Additional-Components#layout)

### Sidebar Layout

The `<Sidebar>` component should be build from `<Sidebar.Section>` subcomponents. All of the details [are described here.](https://github.com/0wczar/react-dashboards/wiki/Bootstrap4-Additional-Components#sidebar)

### Connecting different Sidebars or Navbars to specific routes.

Let's check out how to add an alternative Sidebar to our `ExampleRoute` we created earlier.

1. Let's add the additional Sidebar to `app/layout/components/ExampleSidebar.js` like this:

   \`\`\`jsx

   import React from 'react';

   import { Sidebar } from './../../components';

export const ExampleSidebar = () => (  { / *Sections compositions for this sidebar* /} { / *(...)* /} );

````
2. Now we can attach the Sidebar to the route. To do this you need to open `app/routes/index.js`, import the newly created Sidebar and add it to the body of `getSidebars` function:
```jsx
import { ExampleSidebar} from './../layout/components/ExampleSidebar';
// (...)
const getSidebars = () => (
    <Switch>
        <Route
            path="/example-route"
            component={ ExampleSidebar}
        />

        { /* Default Sidebar: */}
        <Route
            component={ DefaultSidebar }
        />
    </Switch>
);
````

1. Now the new Sidebar should be loaded when navigated to `/example-route`.
2. Alternative Navbars should be added in the same way. Just instead adding them to `getSidebars`, use the `getNavbars` function to attach them.
3. TIP: Sidebar parts should be defined as reusable components, so you can keep the code DRY between multiple layout parts.

## Styling

You can create modular and non-modular css files. All of the files placed in the `app/styles` directory, won't be transformed to modules. On the other hand if you place the style file in the component/route directory - it will become a CSS Module.

By importing `app/styles/variables` you are able to import all of the Bootstrap variabels and colors.

If you need the colors in a JavaScript form, you need to import the `app/colors.js`. This file contains an object with all of the colors from the SCSS files described by the object keys. Example: `colors['100']` - will return you a gray-100 color, and `colors['primary']` will contain the "primary" color.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://webkom.gitbook.io/spin/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.