oss.now: Connecting Open Source Projects and Contributors Worldwide

A Platform for Discovering, Collaborating on, and Growing Open Source Projects

Bridging the Gap Between Project Owners and Contributors

What is oss.now?

In the world of open source software, there’s a common challenge: project maintainers struggle to find dedicated contributors, while developers looking to get involved often don’t know where to start. That’s where oss.now comes in. It’s a modern platform built specifically to solve this problem, acting as a bridge between those who create open source projects and those who want to contribute to them.

Whether you’re a developer with a project you want to showcase, a maintainer needing help with specific skills, or someone looking to find exciting projects to work on, oss.now provides the tools and community to make those connections happen. It’s more than just a directory—it’s a hub where open source collaboration can thrive.

What Makes oss.now Useful?

oss.now comes with a range of features designed to make open source discovery and collaboration easier for everyone involved:

Finding Projects Easily: You can browse through open source projects and filter them by category (like “web development” or “machine learning”), the technologies they use (such as “JavaScript” or “Python”), and how active they are. This means you won’t waste time scrolling through projects that don’t match your interests or skills.
Connecting with GitHub and GitLab: The platform works seamlessly with GitHub and GitLab, two of the most popular places where developers store their code. This integration lets you link your repositories (storage spaces for code) and shows real-time updates like how many people have “starred” the project, recent changes, and other important stats. This helps both maintainers show off their project’s progress and contributors get a clear picture of what they’re joining.
Announcing Project Updates: When you release a major update or a new version of your project, oss.now lets you announce it to the community. This is a great way to get attention for your hard work and attract new contributors who might be interested in the latest features.
Early Project Submissions: If you’re working on a new project that’s not quite ready for a full launch, you can submit it early to oss.now. This gives you more visibility from the start, helping you build a community around your project while it’s still growing.
Matching Contributors and Projects: One of the trickiest parts of open source is finding the right people for the job. oss.now helps project owners find contributors with the specific skills their project needs, whether that’s expertise in a particular programming language, design skills, or experience with certain tools.

The Technology Behind oss.now

oss.now is built using a set of modern tools and technologies that work together to create a smooth, reliable experience. Here’s a breakdown of what powers the platform, explained in simple terms:

Frontend (What You See): The part of the platform you interact with is built using Next.js 15 (with App Router), React 19, TypeScript, and Turbopack. Think of Next.js as the foundation that holds the website together, React as the tool that makes buttons, forms, and other elements work, TypeScript as a helper that catches mistakes in the code, and Turbopack as a tool that makes the website load faster during development.
Styling (How It Looks): The design of oss.now uses Tailwind CSS and shadcn/ui components. Tailwind CSS is like a set of pre-made styles that developers can mix and match to create the look of the site without writing a lot of custom code. shadcn/ui provides ready-to-use parts like buttons, cards, and menus, ensuring the site looks consistent and professional.
Checking Code Quality: To make sure the code is clean and works well, oss.now uses Prettier and ESLint. Prettier formats the code so it looks neat and consistent, while ESLint checks for common mistakes and enforces good coding habits.
Backend (What Happens Behind the Scenes): The “brain” of the platform runs on tRPC and Node.js. Node.js is a runtime that lets developers use JavaScript (a common programming language) to build the server-side part of the website. tRPC ensures that the frontend (what you see) and backend (what happens behind the scenes) can communicate smoothly without errors.
Storing Data: All the information on oss.now—like user accounts, project details, and comments—is stored in a PostgreSQL database, managed through Neon. DrizzleORM is used to organize and interact with this data, making sure it’s stored correctly and easy to retrieve.
Speeding Things Up: To make the platform faster, oss.now uses Redis (via Upstash) for caching. Caching stores frequently used information in a way that’s quick to access, so you don’t have to wait as long for pages to load.
Logging In: oss.now uses Better-Auth with GitHub and GitLab OAuth. This means you can log in using your existing GitHub or GitLab account instead of creating a new one, making the process quicker and more secure.
Tracking Usage: The platform uses Databuddy for analytics, which helps the team understand how people are using oss.now and make improvements based on that data.
Putting It Online: oss.now is hosted on Vercel, a service that makes it easy to deploy and run web applications.
Managing the Codebase: The project is organized as a monorepo (a single repository containing multiple projects) using Turborepo. This helps keep the code organized and makes it easier for developers to work on different parts of the platform.

How the Project is Organized

oss.now’s code is structured in a way that makes it easy for developers to navigate and work on. Here’s a simple breakdown of the main folders and what they contain:

ossdotnow/
├── apps/
│   └── web/          # The main Next.js website application
├── packages/
│   ├── api/          # The code for the API (how the frontend and backend talk)
│   ├── auth/         # The code that handles logging in and user authentication
│   ├── db/           # The database setup, including how data is structured and updated
│   ├── env/          # Code that checks environment variables (secret settings) are correct
│   └── ui/           # Reusable parts of the website, like buttons and forms
└── turbo.json        # Settings for Turborepo, which manages the monorepo

apps/web: This is where the main website lives. It includes all the pages you see when you visit oss.now, like the homepage, project listings, and user profiles.
packages/api: This folder contains the code for the API (Application Programming Interface), which acts as a messenger between the frontend (what you see) and the backend (the server and database). It ensures that when you click a button or submit a form, the right information is sent to the right place.
packages/auth: This handles everything related to user authentication—logging in with GitHub or GitLab, keeping users logged in, and making sure only authorized users can access certain parts of the platform.
packages/db: Here, you’ll find the “schema” (the structure of the database) and “migrations” (code that updates the database when the structure changes). This ensures that data is stored in a way that makes sense and can be easily accessed.
packages/env: Environment variables are like secret settings (such as API keys or database passwords) that the platform needs to work. This folder contains code that checks these variables to make sure they’re set correctly and are valid.
packages/ui: This folder has reusable UI components—things like buttons, input fields, and cards—that are used across the website. Using reusable components ensures that the site looks consistent and saves developers time.

Getting Started with oss.now: Setting Up the Project on Your Computer

If you want to run oss.now on your own computer (for development or testing), here’s a step-by-step guide to get you started. You don’t need to be an expert, but you will need a few tools first.

What You’ll Need

Before you start, make sure you have these tools installed:

Bun: A fast tool for running and managing JavaScript projects. You’ll need version 1.2.13 or higher. You can download it from bun.sh.
Docker: A tool that helps run databases (PostgreSQL and Redis) on your computer without complicated setup. You can get it from docker.com.
Git: A tool for working with code repositories. It’s usually pre-installed on most computers, but if not, you can download it from git-scm.com.

Step 1: Get the Code

First, you need to make a copy of the oss.now code on your computer. This is called “cloning the repository.”

Open a terminal (a program for running commands) and type:

git clone https://github.com/ossdotnow/ossdotnow.git
cd ossdotnow

The first command makes a copy of the code from GitHub to your computer. The second command moves you into the folder where the code is stored.

Step 2: Install Dependencies

Next, you need to install the “dependencies”—extra pieces of code that oss.now needs to work. With Bun, this is easy:

bun install

This command will download and install all the necessary dependencies. It might take a few minutes, so be patient.

Step 3: Set Up Environment Variables

oss.now needs some secret settings (like database passwords and API keys) to work. These are stored in a file called .env.

The project comes with a sample file called .env.example that shows you what settings you need. Make a copy of this file and name it .env:

On Windows: copy .env.example .env
On Mac or Linux: cp .env.example .env

Then, open the .env file in a text editor and replace the example values with your own. You’ll need to get some of these values later (like GitHub and GitLab OAuth keys), but you can fill them in as you go.

Step 4: Start the Databases

oss.now uses two databases: PostgreSQL (for storing most data) and Redis (for caching). With Docker, you can start these databases easily:

bun docker:up

This command tells Docker to start containers (like small, isolated programs) for PostgreSQL and Redis. You’ll see some messages in the terminal as they start up.

Step 5: Set Up the Database Structure

Now that the databases are running, you need to set up their structure (tables, columns, etc.). This is done with “migrations”:

bun db:migrate

This command runs the migration files, which create all the necessary tables in the database.

Step 6: Add Sample Data (Optional)

If you want to test the platform with some sample data (like fake users and projects), you can “seed” the database:

bun db:seed

This adds sample information to the database, making it easier to see how the platform works without having to create everything from scratch.

Step 7: Start the Development Server

Finally, you can start the website on your computer:

bun dev

After a few seconds, you’ll see a message saying the server is running. You can then open your web browser and go to http://localhost:3000 to see oss.now in action!

Useful Commands for Working with oss.now

Once you have the project set up, there are several commands you can use to manage it. Here’s what each one does, in simple terms:

For Development

bun dev: Starts the development server. This is what you use when you’re working on the code—any changes you make will show up immediately in your browser (no need to restart the server).
bun build: Prepares the code for “production” (when you want to put the website online for everyone to use). This optimizes the code to make it run faster.
bun start: Runs the production version of the website (after you’ve built it with bun build).

For Managing the Database

bun docker:up: Starts the PostgreSQL and Redis containers (databases) using Docker.
bun docker:down: Stops the database containers (but keeps the data they’ve stored).
bun docker:clean: Stops the containers and deletes all the data they’ve stored. Use this if you want to start fresh with the databases.
bun db:generate: Creates new migration files. Migrations are like instructions for how to change the database structure (e.g., adding a new table or column).
bun db:migrate: Runs all the migration files to update the database structure.
bun db:push: Quickly updates the database structure without creating migration files. This is only for development (not for production) because it’s less safe.
bun db:studio: Opens Drizzle Studio, a visual tool that lets you view and manage the database. It’s like a spreadsheet for your database, making it easy to see what data is stored and make changes.
bun db:seed: Adds sample data to the database (like test users and projects).
bun db:make-all-admin: Gives admin privileges to all users in the database. This is only for development, so you can test admin features without creating a special admin account.

For Checking Code Quality

bun lint: Runs ESLint, a tool that checks for mistakes and bad habits in the code. It will tell you if there are issues you need to fix.
bun format: Uses Prettier to format the code, making it look neat and consistent. This is like an auto-formatting tool for your code.
bun typecheck: Runs TypeScript to check for type errors. TypeScript helps catch mistakes where variables are used incorrectly (e.g., trying to use a number as a word).

Setting Up Login with GitHub and GitLab

oss.now lets users log in using their GitHub or GitLab accounts. To make this work on your local version of the platform, you need to set up “OAuth” for both services. OAuth is a secure way for apps to let users log in using accounts from other websites.

Setting Up GitHub OAuth

Go to the GitHub Developer Settings in your web browser. You’ll need to be logged into your GitHub account.
Click “New OAuth App” to create a new application.
Fill in the details:
- Application name: You can use oss.now (Development) (this is just for your reference).
- Homepage URL: http://localhost:3000 (this is where your local version of oss.now is running).
- Authorization callback URL: http://localhost:3000/api/auth/callback/github (this is where GitHub will send users after they log in).
Click “Register application” to create it.
You’ll see a “Client ID” (like a username for your app) and a “Client Secret” (like a password). Copy these values and paste them into your .env file (look for GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET).

Setting Up GitLab OAuth

Go to GitLab Applications in your web browser (log into your GitLab account first).
Click “New application” to create a new one.
Fill in the details:
- Name: oss.now (Development) (for your reference).
- Redirect URI: http://localhost:3000/api/auth/callback/gitlab (where GitLab will send users after login).
- Scopes: These are permissions that oss.now needs to access your GitLab information. Check the boxes for api, read_api, read_user, read_repository, openid, profile, and email.
Click “Save application” to create it.
You’ll see an “Application ID” (Client ID) and a “Secret”. Copy these and paste them into your .env file (look for GITLAB_CLIENT_ID and GITLAB_CLIENT_SECRET).

Once you’ve set up both, you should be able to log in to your local oss.now using your GitHub or GitLab account.

How to Contribute to oss.now

oss.now is an open source project itself, which means anyone can contribute to making it better. Whether you’re a developer, designer, or just someone who has ideas for improvements, your contributions are welcome! Here’s how to get started.

The Basic Workflow

Fork the Repository: A “fork” is a copy of the oss.now repository under your own GitHub account. This lets you make changes without affecting the original project. To fork it, go to the oss.now GitHub page and click the “Fork” button in the top-right corner.
Create a New Branch: Once you have your fork, you’ll want to create a new “branch” to work on your changes. A branch is like a separate copy of the code where you can make edits without messing up the main codebase.

First, make sure you’re on the dev branch (this is where all development happens, not main). Then create a new branch:
```
git checkout -b feature/your-feature-name
```
Replace your-feature-name with a short description of what you’re working on (e.g., feature/add-search-filter).
Make Your Changes: Now you can start making changes to the code. Whether it’s fixing a bug, adding a new feature, or improving the documentation, take your time and make sure your changes work as expected.
Check Your Work: Before submitting your changes, it’s important to make sure they meet the project’s standards:
- Run bun lint to check for code style issues.
- Run bun typecheck to make sure there are no TypeScript errors.
- Test your changes by running the development server (bun dev) and making sure everything works as it should.
Commit Your Changes: When you’re happy with your work, “commit” your changes. This saves them with a message explaining what you did. Use a clear, descriptive message so others can understand your changes:
```
git add .
git commit -m "Add a search filter for project categories"
```
Push and Create a Pull Request: Push your branch to your fork on GitHub:
```
git push origin feature/your-feature-name
```
Then, go to the original oss.now repository on GitHub. You’ll see a button to “Compare & pull request” for your new branch. Click it, fill in details about your changes, and submit the pull request. The oss.now team will review your changes and, if everything looks good, merge them into the project!

Important Things to Remember

Always work from the dev branch, not main. The main branch is for the stable, production version of the platform, while dev is where new features and fixes are developed.
If you have other Next.js apps running on your computer, stop them before working on oss.now. They might use the same port (3000) and cause problems with logging in (OAuth flows).
Right now, the production version of oss.now is in development mode to keep it private. This might change as the project grows, but for now, focus on contributing to the dev branch.

Putting oss.now Online (Deployment)

oss.now is designed to be easy to deploy on Vercel, a popular platform for hosting web applications. Here’s how to do it:

Fork the Repository: If you haven’t already, fork the oss.now repository to your GitHub account (as explained in the contributing section).
Import the Project to Vercel: Go to Vercel and sign up or log in. Click “New Project” and import your forked oss.now repository.
Set Up Environment Variables: In the Vercel dashboard for your project, go to the “Settings” tab and then “Environment Variables”. Add all the variables from your local .env file, making sure to use production values (not your local development ones).
Deploy: Click “Deploy” and Vercel will build and publish your version of oss.now. After a few minutes, your site will be live!

Tips for Production Deployments

Update OAuth Callback URLs: Make sure to update the callback URLs for GitHub and GitLab OAuth to use your production domain (e.g., https://your-oss-now.vercel.app/api/auth/callback/github instead of localhost).
Use Production Databases: For a live site, use real production instances of PostgreSQL (like Neon) and Redis (like Upstash) instead of local Docker containers. This ensures your data is safe and accessible.
Set VERCEL_ENV=production: In your environment variables, set VERCEL_ENV to production to enable production-specific features and settings.

How oss.now is Built (Architecture)

Understanding how oss.now is structured can help you work with the code or just appreciate how it all comes together. Let’s break it down into frontend (what you see) and backend (what happens behind the scenes).

Frontend: The User Interface

Next.js 15 with App Router: Next.js is the framework that powers the frontend. The App Router helps organize the website’s pages and handles “server-side rendering,” which means pages are built on the server before being sent to your browser. This makes the site faster and better for search engines.
React 19: React is a library for building interactive user interfaces. It lets developers create reusable components (like buttons or forms) that can be used across the site, making the code more efficient.
TanStack Query: This tool helps with fetching and caching data from the backend. For example, when you load a list of projects, TanStack Query makes sure the data is stored temporarily (cached) so you don’t have to wait for it to load again if you navigate away and come back.
Tailwind CSS: As mentioned earlier, Tailwind CSS is used for styling. It provides a set of pre-defined classes that developers can use to style elements without writing custom CSS, ensuring the site looks consistent.
shadcn/ui Components: These are pre-built, reusable UI components (like modals, dropdowns, and input fields) that save time and keep the design consistent.

Backend: The Server and Data

tRPC: tRPC (TypeScript Remote Procedure Call) helps the frontend and backend communicate in a type-safe way. This means when the frontend sends a request to the backend, both sides agree on what data will be sent and received, reducing errors.
DrizzleORM: This is an “ORM” (Object-Relational Mapper), which is a tool that makes it easier to work with databases. Instead of writing complex database queries, developers can use simple JavaScript code to interact with the database.
Better-Auth: This handles all the authentication logic, like logging in with GitHub or GitLab, managing user sessions, and keeping user data secure.
Upstash Redis: Redis is used for caching and “rate limiting.” Rate limiting prevents a single user from making too many requests to the server (which could slow it down), keeping the platform stable.

Database Structure

The database for oss.now is organized into several tables to store different types of information:

Users and Authentication: Stores user accounts, including details from their GitHub/GitLab profiles and authentication tokens.
Projects: Contains information about open source projects, including their name, description, category, technologies used, and links to their repositories.
Submissions and Waitlist: Tracks projects that have been submitted to oss.now, including those waiting for approval.
Project Launches and Comments: Stores announcements about project releases and comments from users on those announcements.
Voting and Reporting: Allows users to vote on projects they like and report inappropriate content.

Troubleshooting: Common Issues and How to Fix Them

Even with careful setup, you might run into problems when working with oss.now. Here are some common issues and how to solve them:

1. OAuth Redirect Issues

If you try to log in with GitHub or GitLab and get an error, or if you’re redirected to the wrong page, here’s what to check:

Port Conflicts: Make sure no other Next.js apps are running on port 3000. Only one app can use a port at a time, so if another app is using 3000, oss.now won’t be able to handle the OAuth redirects properly. Close any other apps using port 3000 and try again.
Callback URLs Must Match Exactly: The callback URL you entered in GitHub/GitLab must be exactly the same as the one in your oss.now setup. Even a small difference (like a missing slash or http instead of https) will cause the redirect to fail. Double-check that the URLs match.

2. Database Connection Errors

If you get errors saying oss.now can’t connect to the database, try these steps:

Check Docker is Running: The PostgreSQL and Redis databases are run through Docker, so make sure Docker is open and running on your computer. If Docker isn’t running, bun docker:up won’t work.
Verify PostgreSQL Port: PostgreSQL runs on port 5432 by default. Make sure no other program is using this port, as that would block oss.now from connecting. You can check for port conflicts using tools like lsof (on Mac/Linux) or netstat (on Windows).
Check DATABASE_URL: The DATABASE_URL in your .env file tells oss.now how to connect to the database. Make sure it’s correct. For a local Docker setup, it should look something like postgresql://postgres:postgres@localhost:5432/ossnow?sslmode=disable.

3. Environment Variable Errors

If you see errors about missing or invalid environment variables:

Check All Required Variables: The .env.example file lists all the variables you need. Make sure you’ve copied them to .env and filled in the values. Required variables are usually marked, but if in doubt, check the error message—it will tell you which variable is missing.
Run bun dev to Find Errors: The development server (started with bun dev) will check your environment variables and show you any that are missing or invalid. This is a quick way to identify problems.

License

oss.now is licensed under the MIT License. This is a permissive license that allows you to use, modify, and distribute the software, as long as you include a copy of the license and credit the original authors. You can find the full license text in the LICENSE file in the repository.

In simple terms, the MIT License means you’re free to use oss.now for any purpose—personal, commercial, or educational. You can make changes to the code and even distribute your modified version, as long as you include the original license.

Acknowledgments

oss.now wouldn’t be possible without the hard work of many developers and the tools they’ve created. Here are some of the key tools and services that power the platform:

Next.js: A powerful framework for building modern web applications, developed by Vercel.
shadcn/ui: A collection of beautiful, reusable UI components that help create a consistent look and feel.
Neon: Provides the PostgreSQL database that stores all of oss.now’s data.
Vercel: Hosts the oss.now platform, making it accessible to users around the world.

Made with ❤️ by the oss.now team

oss.now: Revolutionizing Open Source Collaboration with GitHub & GitLab Integration