README.md 5.75 KB
Newer Older
Sandro Lutz's avatar
Sandro Lutz committed
1
# amiv Website
2

Sandro Lutz's avatar
Sandro Lutz committed
3
This is the home of the amiv website.
4
5
6

## 🚀 Quick start

Sandro Lutz's avatar
Sandro Lutz committed
7
1. **Development**
8

Sandro Lutz's avatar
Sandro Lutz committed
9
   Navigate into the project directory, install all dependencies and run the development server using the following commands:
Sandro Lutz's avatar
Sandro Lutz committed
10

Sandro Lutz's avatar
Sandro Lutz committed
11
   _Please note that the parameter `-g` is optional. It is being used to install the package `gatsby-cli` globally on the system._
12

Sandro Lutz's avatar
Sandro Lutz committed
13
14
15
16
17
   ```shell
   npm install -g gatsby-cli
   npm install
   gatsby develop
   ```
18

Sandro Lutz's avatar
Sandro Lutz committed
19
   You can visit the website now at http://localhost:8000
Sandro Lutz's avatar
Sandro Lutz committed
20

Sandro Lutz's avatar
Sandro Lutz committed
21
2. **Development with Devcontainer (VSCode)**
22

Sandro Lutz's avatar
Sandro Lutz committed
23
   You can run the prepared development environment with docker and VSCode without the need to install anything project-specific on your system.
24

Sandro Lutz's avatar
Sandro Lutz committed
25
   Requirements:
26

Sandro Lutz's avatar
Sandro Lutz committed
27
28
29
30
   * *(Windows only)* [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/)
   * [Docker Engine](https://docs.docker.com/engine/install/)
   * [Visual Studio Code](https://code.visualstudio.com/)(VSCode)
   * [Remote Development Extension Pack for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack)
31

Sandro Lutz's avatar
Sandro Lutz committed
32
   Open the project directory with the prepared devcontainer by clicking the green button in the left button corner of the VSCode window and select `Remote-Containers: Open Folder in Container...`.
33

Sandro Lutz's avatar
Sandro Lutz committed
34
35
36
37
38
   On startup, `yarn install` is run automatically. You can start the gatsby development process with `gatsby develop`.

   You can visit the website now at http://localhost:8000

   **IMPORTANT:** You also have to run the backend project on your machine! It is not possible to use an externally hosted backend.
39
40

3. **Linting & Formatting**
41

Sandro Lutz's avatar
Sandro Lutz committed
42
   We use `eslint` and `prettier` for linting and formatting of the javascript code. You can use the following commands:
43

Sandro Lutz's avatar
Sandro Lutz committed
44
45
46
47
   ```shell
   npm run eslint
   npm run format
   ```
48

49
4. **Production Build**
50

Sandro Lutz's avatar
Sandro Lutz committed
51
   You can prepare a production build manually and serve it using gatsby's built-in webserver. This will run the server-side rendering part.
52

Sandro Lutz's avatar
Sandro Lutz committed
53
   It is very possible, that some things do not work correctly when ssr is used, so you should definitively test this one before deploying a new version!
54

Sandro Lutz's avatar
Sandro Lutz committed
55
56
57
58
   ```shell
   gatsby build
   gatsby serve
   ```
Sandro Lutz's avatar
Sandro Lutz committed
59

Sandro Lutz's avatar
Sandro Lutz committed
60
   For more information about deployment, read the section about deployment below.
61
62
63

## 🧐 What's inside?

Sandro Lutz's avatar
Sandro Lutz committed
64
A quick look at the most important files and directories of the project.
Sandro Lutz's avatar
Sandro Lutz committed
65
66
67
68
69
70
71
72
73
74
75

```ascii
.
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.js
├── config.development.js
├── config.production.js
└── src
    ├── components
Sandro Lutz's avatar
Sandro Lutz committed
76
    ├── content
Sandro Lutz's avatar
Sandro Lutz committed
77
    ├── context
Sandro Lutz's avatar
Sandro Lutz committed
78
    ├── hooks
Sandro Lutz's avatar
Sandro Lutz committed
79
80
81
82
83
84
85
86
87
    ├── images
    ├── intl
    ├── pages
    ├── store
    ├── utils
    └── theme.js
```

1. **`gatsby-browser.js`**: This file is where Gatsby expects to find any usage of the [Gatsby browser APIs](https://www.gatsbyjs.org/docs/browser-apis/). These allow customization/extension of default Gatsby settings affecting the browser.
88

Sandro Lutz's avatar
Sandro Lutz committed
89
2. **`gatsby-config.js`**: This is the main configuration file for the Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. (Check out the [config docs](https://www.gatsbyjs.org/docs/gatsby-config/) for more detail).
90

Sandro Lutz's avatar
Sandro Lutz committed
91
3. **`gatsby-node.js`**: This file is where Gatsby expects to find any usage of the [Gatsby Node APIs](https://www.gatsbyjs.org/docs/node-apis/). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.
92

Sandro Lutz's avatar
Sandro Lutz committed
93
4. **`gatsby-ssr.js`**: This file is where Gatsby expects to find any usage of the [Gatsby server-side rendering APIs](https://www.gatsbyjs.org/docs/ssr-apis/). These allow customization of default Gatsby settings affecting server-side rendering.
94

Sandro Lutz's avatar
Sandro Lutz committed
95
5. **`config.development.js` / `config.production.js`**: This file contains configuration values used with our custom components and pages.
96

Sandro Lutz's avatar
Sandro Lutz committed
97
6. **`/src`**: This directory contains all source code.
98

Sandro Lutz's avatar
Sandro Lutz committed
99
100
101
102
103
104
105
   1. **`/src/components`**: Contains all components used somewhere on the website.
   2. **`/src/content`**: All content only files (e.g. board or teams portraits or static texts)
   3. **`/src/context`**: Custom [React Context](https://reactjs.org/docs/context.html)
   4. **`/src/hooks`**: Custom React hooks.
   5. **`/src/images`**: Static images.
   6. **`/src/intl`**: Translation files used by `react-intl`.
   7. **`/src/pages`**: Every `js` file represents a page which path is exactly like the folder structure and filename.
106

Sandro Lutz's avatar
Sandro Lutz committed
107
      **Note**: Every file starting with an underscore (`_`) in the pages directory is ignored. Those pages are mostly being used for client-only routes. Therefore no page route is created and no server-side rendering performed.
Sandro Lutz's avatar
Sandro Lutz committed
108

Sandro Lutz's avatar
Sandro Lutz committed
109
      _Example: The file `/src/pages/amiv/about.js` will serve the component defined in that file as a page at the path `/amiv/about`._
110

Sandro Lutz's avatar
Sandro Lutz committed
111
112
   8. **`/src/store`**: This directory contains all files related to data handling using `react-redux`.
   9. **`/src/utils`**: Collection of utility functions.
Sandro Lutz's avatar
Sandro Lutz committed
113
   10. **`/src/theme.js`**: Theme definition for light/dark mode (dimensions, colors, etc.)
114

Sandro Lutz's avatar
Sandro Lutz committed
115
## 💫 Deployment
116

Sandro Lutz's avatar
Sandro Lutz committed
117
TODO: Add information about the deployment process of the project.
118

Sandro Lutz's avatar
Sandro Lutz committed
119
## ⚙ Technologies
120

Sandro Lutz's avatar
Sandro Lutz committed
121
### Frontend Frameworks & Libraries
122

Sandro Lutz's avatar
Sandro Lutz committed
123
124
125
126
- [Gatsby](https://www.gatsbyjs.org)
- [React](https://reactjs.org/)
- [react-intl](https://github.com/formatjs/react-intl)
- [React-Redux](https://react-redux.js.org/)
127

Sandro Lutz's avatar
Sandro Lutz committed
128
### Backend
129

Sandro Lutz's avatar
Sandro Lutz committed
130
- [AMIV API](https://github.com/amiv-eth/amivapi)
131

Sandro Lutz's avatar
Sandro Lutz committed
132
### Build Tools
133

Sandro Lutz's avatar
Sandro Lutz committed
134
135
- [NPM](https://www.npmjs.com/)
- [gatsby-cli](https://www.npmjs.com/package/gatsby-cli)
136

Sandro Lutz's avatar
Sandro Lutz committed
137
### Development Tools
138

Sandro Lutz's avatar
Sandro Lutz committed
139
140
- [ESlint](https://github.com/eslint/eslint)
- [Prettier](https://github.com/prettier/prettier)
141

Sandro Lutz's avatar
Sandro Lutz committed
142
  Most IDEs have plugins for those tools. VS Code is the recommended IDE.