README.md 5.63 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
   ```shell
12
13
   yarn global add gatsby-cli
   yarn install
Sandro Lutz's avatar
Sandro Lutz committed
14
15
   gatsby develop
   ```
16

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

Sandro Lutz's avatar
Sandro Lutz committed
19
2. **Development with Devcontainer (VSCode)**
20

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

Sandro Lutz's avatar
Sandro Lutz committed
23
   Requirements:
24

Sandro Lutz's avatar
Add AF    
Sandro Lutz committed
25
26
27
28
   - _(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)
29

Sandro Lutz's avatar
Sandro Lutz committed
30
   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...`.
31

Sandro Lutz's avatar
Sandro Lutz committed
32
33
34
35
36
   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.
37
38

3. **Linting & Formatting**
39

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

Sandro Lutz's avatar
Sandro Lutz committed
42
   ```shell
43
44
   yarn run eslint
   yarn run format
Sandro Lutz's avatar
Sandro Lutz committed
45
   ```
46

47
4. **Production Build**
48

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

Sandro Lutz's avatar
Sandro Lutz committed
51
   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!
52

Sandro Lutz's avatar
Sandro Lutz committed
53
54
55
56
   ```shell
   gatsby build
   gatsby serve
   ```
Sandro Lutz's avatar
Sandro Lutz committed
57

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

## 🧐 What's inside?

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

```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
74
    ├── content
Sandro Lutz's avatar
Sandro Lutz committed
75
    ├── context
Sandro Lutz's avatar
Sandro Lutz committed
76
    ├── hooks
Sandro Lutz's avatar
Sandro Lutz committed
77
78
79
80
81
82
83
84
85
    ├── 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.
86

Sandro Lutz's avatar
Sandro Lutz committed
87
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).
88

Sandro Lutz's avatar
Sandro Lutz committed
89
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.
90

Sandro Lutz's avatar
Sandro Lutz committed
91
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.
92

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

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

Sandro Lutz's avatar
Sandro Lutz committed
97
98
99
100
101
102
103
   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.
104

Sandro Lutz's avatar
Sandro Lutz committed
105
      **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
106

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

Sandro Lutz's avatar
Sandro Lutz committed
109
110
   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
111
   10. **`/src/theme.js`**: Theme definition for light/dark mode (dimensions, colors, etc.)
112

Sandro Lutz's avatar
Sandro Lutz committed
113
## 💫 Deployment
114

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

Sandro Lutz's avatar
Sandro Lutz committed
117
## ⚙ Technologies
118

Sandro Lutz's avatar
Sandro Lutz committed
119
### Frontend Frameworks & Libraries
120

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

Sandro Lutz's avatar
Sandro Lutz committed
126
### Backend
127

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

Sandro Lutz's avatar
Sandro Lutz committed
130
### Build Tools
131

132
133
- [yarn](https://yarnpkg.com/)
- [gatsby-cli](https://yarnpkg.com/package/gatsby-cli)
134

Sandro Lutz's avatar
Sandro Lutz committed
135
### Development Tools
136

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

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