TSB Official Website

Técnico Solar Boat official website open-sourced, built with NextJS, Typescript and Firebase
Explore the docs »

View Website · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Firebase Setup
   • Environment Variables Setup
   • PHP Setup
3. Deploy
4. Roadmap
5. Contributing Guidelines
6. License
7. Contact

About The Project

Features

• Full Page Scroll
• Contact Form
• Machine Learning Interactive Example
• Individual Team Member Profiles
• Gallery
• Open Source Page
• Recruitment Page

Built With

Front-end of the application was developed with:

• TypeScript
• NextJS

Back-end of the application was developed with:

• Firebase
• PHP

Getting Started

Initial Setup

1. Setup fnm as NodeJS Manager -> Install
2. Install NodeJS v20

fnm install 20 # Installs NodeJS version 20

3. Setup pnpm as Package Manager -> Install

pnpm install # Installs all project dependencies

4. Setup Biome as Linter and formatter -> Install

5. Setup VS Code format on save

(Ctrl + Shift + P) / (Cmd + Shift + P) Preferences: Open User Setting (JSON)

"[javascript]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "biomejs.biome"
  },
"editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },

Local Development

1. To locally run the application

pnpm dev

1. To lint the code before creating a pull request

pnpm lint

Firebase Setup

This website is tightly integrated with our own project management application, which is open-sourced as well, but we provide a public setup example to get you going.

To setup your own database, it only takes 2 min.

1. Create a Firebase Project here with a name your-application
2. Setup Realtime Database (not Firestore)
3. Import the database template from

components/utils/dbTemplate.json

5. Import the database rules from

components/utils/dbRules.json

6. Repeat the above steps to create a development database In development you should use a copy of the original database. In the case something goes wrong, your original DB remains intact. So just repeat these steps for the development database and give it a project name, for example, your-application-dev.

Environment Variables Setup

To protect sensitive information on firebase API keys we take advantage of environment variables, which remain private for developers, while maintaining a public repository. These variables are stored in a .env file in the root of the repository. You can check the template used in template.env and replace all of the variables with your own. Don't forget to rename the file to only .env 😀

If you aren't using a development database, or a firebase token leave those fields empty or remove them, as they are optional for the next step.

Optional

Now let's automate things! The project is already setup to always use the development database while in development, and to use the original database when building for production (check components/Contexts/Firebase.tsx). But we also want the development database to always be up to date with the original one, in order to work with real data.

For this we take advantage of the Firebase CLI to export the data from the original database (your-application) and export it to the development database (your-application-dev)

Install Firebase CLI in your system:

pnpm add -g firebase-tools

You only have to do this once. Retrieve and copy the firebase CLI token from the terminal and add it to the .env variable placeholder:

firebase login:ci

You only have to do this once. Setup the connection to the databases using the provided script, and follow the on-screen instructions:

sh firebase_databases_setup.sh

Last step! Sync your original database with your development one by running our syncing script. This will copy all of the data from the original to the development database:

sh firebase_databases_sync.sh

Since we previously configured the databases, you can now sync the databases whenever you want, without configuring them again.

PHP Setup

All of our API's are located in public/api.

We use PHP's package manager composer to install the required packages. You can install them by changing directory and running

composer install

or by running our custom install script at the root directory level

pnpm install-all

There is one folder protected which we place at the root location of our server, which contains protected keys and values for our php api. We provide a template for it, if you need it.

In order to work with the PHP api you need to locally run a php server / have a production ready server.

Deploy

If you followed all of the above steps, you can proceed to locally run the project with

pnpm dev

If you would like to deploy the application to your own server, run

pnpm build

This will create a out folder. Just copy all of the contents of the folder to the root directory of your server.

Roadmap

See the open issues for a list of proposed features (and known issues), if any.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. To ensure a good workflow for this repository please follow our contributing guidelines:

• Contributing Guidelines

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Dinis Rodrigues - Linkedin - dinis.rodrigues@tecnico.ulisboa.pt