Streamlining Your Next.js Project with Private GitHub/Gitlab Repositories as NPM Packages

Using Private GitHub/Gitlab Repos in Your Next.js Projects

Imagine this scenario: you're working on a super cool Next.js project, and you have some shared code that you'd like to use across multiple projects. You don't really want to make it public by publishing it to npm. You also don't want to pay for an npm account to make your repos private. Is there a way to keep it private, secure, yet reusable? You bet!

In the world of Next.js v13.4 and beyond, using private GitHub or GitLab repositories as npm packages is not only possible, it's also quite straightforward. The steps vary for older versions of Next.js before v13.4 (those using Page Router) and won't be covered in this blog.

Essentially, we’ll be taking code from a private GitHub or GitLab repository and using it directly in our Next.js project. This method is perfect when you have shared components, utilities, or any other code that you need to reuse across several projects, but don't want to expose to the world (or persevere through the overhead of setting up an npm account).

Today, I'll walk you through the steps to make this happen. Buckle up, because we're about to make your life a whole lot easier!

Step 1: Create Your Private GitHub Repo

This is where your shared code will live. If you already have one, fantastic. If not, go ahead and create a new private repository on GitHub or Gitlab.

Step 2: Generate a GitHub Access Token

1. Navigate to your GitHub settings (or Gitlab settings for those using Gitlab).
2. Create a new personal access token (make sure it only has read access).
3. Copy this token and keep it safe (you’ll need it soon).

Step 3: Set Up Your Shared Repo

In your shared repository's package.json, set the name field to whatever you'd like to call your package, e.g., "package-name": "1.0.0".

Step 4: Update Your Next.js Project’s package.json

In the package.json of the Next.js project where you want to use your shared code:

{
  "dependencies": {
    "package-name": "git+https://<github_token>:x-oauth-basic@github.com/<user>/<repo>.git#branch-name"
  }
}

Replace <github_token>, <user>, <repo>, and branch-name with the appropriate values from your setup.

Final Steps: Configuration in Next.js

1. In your next.config.js, add the following:

   module.exports = {
       transpilePackages: ["package-name"],
   };
   

   This tells Next.js to also compile your typescript code from the shared repo and transform it to javascript - that's basically what transpile means; a combination of the word 'transform' and 'compile'. Without this, you'll get module parsing errors for your typescript (.ts) files.

2. If you're using Tailwind CSS, update your tailwind.config.js to include your shared package:

   module.exports = {
       content: [
           "./node_modules/<package_name>/src/**/*.{js,ts,jsx,tsx,html,mdx}",
           "./node_modules/<package_name>/app/**/*.{js,ts,jsx,tsx,html,mdx}",
       ],
       //… other tailwind config
   };
   

   Replace <package_name> with the name of your shared repo. Also, if you aren't using the src folder, feel free to adjust the values according to your setup

3. Now run npm install and voila! your shared package has now been installed as an NPM dependency and you can use it in your project.

Before We Finish Just Yet

Always remember to update the version number in your package.json with a higher value each time you make a change to your shared repo. After words, run npm update <package_name> where <package_name> is the name of your shared package/repo. This will ensure that your changes in the shared package's changes are published to your project.

Conclusion

Incorporating private GitHub repos as npm packages in your Next.js projects not only keeps your code organized and secure but also significantly boosts your productivity. You no longer need to duplicate code or compromise your privacy by publishing sensitive code to public registries.

So, what are you waiting for? Dive in and streamline your projects today. And remember, it’s these smart shortcuts that often make a big difference in the efficiency and success of your development efforts.