README.md 5.05 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
10
    Navigate into the project directory, install all dependencies and run the development server using the following commands:

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
13

    ```shell
Sandro Lutz's avatar
Sandro Lutz committed
14
15
16
    npm install -g gatsby-cli
    npm install
    gatsby develop
17
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

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
2. **Development with Docker**

    You can run the development server completely with docker.

    Build local development image

    ```shell
    docker build -t amiv-website-local-dev -f Dockerfile.development .
    ```

    Run development server with

    ```shell
    docker run --rm -it -p 8000:8000 -v ${PWD}:/app amiv-website-local-dev
    ```

3. **Linting & Formatting**
38

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

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

46
4. **Production Build**
47

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

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

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

    For more information about deployment, read the section about deployment below.
58
59
60

## 🧐 What's inside?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sandro Lutz's avatar
Sandro Lutz committed
131
132
* [NPM](https://www.npmjs.com/)
* [gatsby-cli](https://www.npmjs.com/package/gatsby-cli)
133

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

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

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