UTD Notebook

What am I

Contributing

We are always open to contributions to the project. If you would like to contribute and want some guidance on where to start, please join our Discord and ask for drop a message in the #notebook-general channel or DM Shriram for more details.

Currently, we're tracking all issues via GitHub Issues. If you would like to work on an issue, please comment on the issue and we will assign it to you. If you see anything that you think could be improved, please create an issue and we will look into it.

Tech Stack

• Frontend: Next.js, React, TypeScript, Tailwind CSS
• Validation & Serialization: Zod, SuperJSON
• Authentication: BetterAuth
• State Management: Zustand
• Database: PostgreSQL (Neon), Drizzle ORM

Getting Started

Please make sure you have at least NodeJS v21.1.0 or greater installed before continuing.

Start by cloning the repository to your local machine.

git clone https://github.com/UTDNebula/utd-notebook.git --recurse-submodules

Note

If you already cloned the repository but don't have the src/nebula-library folder, run the following command:

git submodule update --init --recursive

Next, navigate to the project directory and install the dependencies.

cd utd-notebook
npm install

Make sure you have a .env file in the root of the project. If you do not, copy the .env.example file and rename it to .env

Environment Variables

This project uses Better Auth for authentication. Better Auth, with their built-in providers, makes it easy for users to use preexisting logins. Currently, we are using Discord and Google as OAuth Providers, so you will need to create a Client ID and Client Secret for Google and Discord respectively (or remove the providers if you'd like).

Once you have your Client ID and Client Secrets, add them to your .env file.

The BETTER_AUTH_URL variable should be set to http://localhost:3000 for local development. The BETTER_AUTH_SECRET variable should be set to a random string of characters. You can generate one using this website. or by running the following command in your terminal.

openssl rand -hex 32

UTD Notebook uses an ORM called Drizzle to interact with the database. In order to connect to the database, you will need to add the DATABASE_URL variable to your .env file. Your project lead will give this to you upon request.

The Nebula API is used for file storage. The NEBULA_API_URL variable should be set to https://api.utdnebula.com/ and the NEBULA_API_STORAGE_BUCKET variable to notebook. An API key and storage key should be requested from the project lead for the NEBULA_API_KEY and NEBULA_API_STORAGE_KEY variables.

Finally, start the development server.

npm run dev

Branching

When working on a new feature, please create a new branch with the following naming convention:

git checkout -b feature/<feature-name>

When you are ready to merge your branch into the develop branch, please create a pull request and request a review from the Notebook Dev Team. Please include details about what issue you are addressing with the pull request, what changes you made, and any other relevant information.

Nebula Library

When working in the src/nebula-library folder, you are working in a shared component library that is part of a nested Git repository. Follow these steps to create a secondary pull request (PR) for your library changes:

1. Checkout a branch

cd src/nebula-library
# Replace <feature-name> with a branch name
git checkout -b feature/<feature-name>

2. Make your changes in the src/nebula-library folder

3. Push your changes

git push
cd ../..

4. Make a pull request in the nebula-library repository

Make a PR from your branch into main at github.com/UTDNebula/nebula-library and request your project lead as a reviewer.

Wait for your PR to be approved.

Tip

In the meantime, you can make a regular PR on the UTD Notebook repository. Its checks and build may not pass without your changes in src/nebula-library, so you can switch the branch and push with the following commands:

# Replace <feature-name> with the feature name you used in step 1
git submodule set-branch --branch feature/<feature-name> src/nebula-library
git push

If you do this, just make sure to run the following command before the next step:

git submodule set-branch --default src/nebula-library

5. After your nebula-library pull request is merged…

Pull your changes from the library and push them to Notebook. Then make a regular PR on Notebook.

git submodule update --recursive --remote
git push