diff --git a/.env.example b/.env.example new file mode 100644 index 0000000000..44edc8e6ce --- /dev/null +++ b/.env.example @@ -0,0 +1,33 @@ +# visit https://giscus.app to get your Giscus ids +NEXT_PUBLIC_GISCUS_REPO= +NEXT_PUBLIC_GISCUS_REPOSITORY_ID= +NEXT_PUBLIC_GISCUS_CATEGORY= +NEXT_PUBLIC_GISCUS_CATEGORY_ID= +NEXT_PUBLIC_UTTERANCES_REPO= +NEXT_PUBLIC_DISQUS_SHORTNAME= + + +MAILCHIMP_API_KEY= +MAILCHIMP_API_SERVER= +MAILCHIMP_AUDIENCE_ID= + +BUTTONDOWN_API_KEY= + +CONVERTKIT_API_KEY= +# curl https://api.convertkit.com/v3/forms?api_key= to get your form ID +CONVERTKIT_FORM_ID= + +KLAVIYO_API_KEY= +KLAVIYO_LIST_ID= + +REVUE_API_KEY= + +# Create EmailOctopus API key at https://emailoctopus.com/api-documentation +EMAILOCTOPUS_API_KEY= +# List ID can be found in the URL as a UUID after clicking a list on https://emailoctopus.com/lists +# or the settings page of your list https://emailoctopus.com/lists/{UUID}/settings +EMAILOCTOPUS_LIST_ID= + +# Create Beehiiv API key at https://developers.beehiiv.com/docs/v2/bktd9a7mxo67n-create-an-api-key +BEEHIIV_API_KEY= +BEEHIIV_PUBLICATION_ID= diff --git a/.gitignore b/.gitignore index f62bbb9aeb..ad317a1bf9 100644 --- a/.gitignore +++ b/.gitignore @@ -39,6 +39,7 @@ yarn-debug.log* yarn-error.log* # local env files +.env .env.local .env.development.local .env.test.local diff --git a/data/authors/ana-stengel.mdx b/data/authors/ana-stengel.mdx new file mode 100644 index 0000000000..50ffbbecdc --- /dev/null +++ b/data/authors/ana-stengel.mdx @@ -0,0 +1,8 @@ +--- +name: Ana Stengel +avatar: /static/images/danieldanielecki.png +occupation: Developer +company: Ditectrev +--- + +Guest author on the Ditectrev Blog. diff --git a/data/blog/operating-system/runtime-environment/node-js/how-to-add-a-npmrc-file-step-by-step.mdx b/data/blog/operating-system/runtime-environment/node-js/how-to-add-a-npmrc-file-step-by-step.mdx new file mode 100644 index 0000000000..4febf72f07 --- /dev/null +++ b/data/blog/operating-system/runtime-environment/node-js/how-to-add-a-npmrc-file-step-by-step.mdx @@ -0,0 +1,274 @@ +--- +title: 'How to Add a .npmrc File (Step-by-Step)' +date: '2026-02-01' +tags: ['javascript', 'node', 'nodejs', 'npm', 'operating system', 'package manager', 'runtime environment'] +draft: false +summary: 'Learn what a .npmrc file is, why it matters in Node.js projects, and how to add and use it correctly for npm configuration, private packages, and custom registries. Step-by-step guide with examples.' +authors: ['ana-stengel'] +images: ['/static/images/nodejs-npmrc.jpg'] +layout: PostLayout +--- + + + +## Introduction + +Node.js is one of the most popular runtimes for building modern web applications—fast, flexible, and suited to both small and large projects. When working with Node.js, developers rely on **npm** (Node Package Manager) to install and manage dependencies. One important but often overlooked part of the npm ecosystem is the **`.npmrc`** file. + +Many developers are unsure what a `.npmrc` file is or why it matters. Even experienced engineers sometimes underuse it. This guide explains what a `.npmrc` file is, why it is useful, where to place it, and how to add and manage it step by step. For additional community discussion and real-world Q&A, see [How can I add a .npmrc file?](https://stackoverflow.com/questions/42877722/how-can-i-add-a-npmrc-file) on Stack Overflow. + +## What Is a .npmrc File? + +A **`.npmrc`** file is a configuration file used by npm. It tells npm how to behave. Settings are written in a simple **key=value** format. + +For example, the `.npmrc` file can store: + +- **Registry URLs** – where to download packages from +- **Authentication tokens** – for private or scoped registries +- **Package scopes** – which registry to use for which scope +- **Proxy settings** – for corporate or restricted networks +- **Cache and save rules** – how to cache and record dependencies + +In short, it lets you control how npm installs and manages packages without repeating long flags in every command. + +The file is plain text and can be created with any editor. The leading dot (`.`) makes it a hidden file on Unix-like systems (macOS, Linux). + +## Why Is the .npmrc File Important? + +The `.npmrc` file becomes important as soon as you work on real projects. Common reasons to use it: + +### 1. Using Private Packages + +Many teams use private npm packages. To access them, npm needs authentication. The `.npmrc` file is where you store these credentials (preferably via environment variables, not raw tokens in the repo). + +### 2. Custom Registries + +By default, npm uses the public registry at `https://registry.npmjs.org/`. You may need a different registry—for example a company registry or a mirror. The `.npmrc` file lets you switch registries per project or per scope. + +### 3. Project-Level Settings + +Different projects may need different registries, save rules, or engine checks. A `.npmrc` in the project root applies only to that project and keeps settings next to the code. + +### 4. Saving Time and Reducing Errors + +Without `.npmrc`, you might type long `--registry` or `--save-exact` options every time. With the file in place, npm reads the settings automatically and your workflow stays consistent. + +## Where Can You Add a .npmrc File? + +Where you put `.npmrc` determines **scope**: who or which project is affected. + +### Global Level + +- Affects all users on the machine. +- Usually managed by system administrators. +- Rarely used by everyday developers. + +### User Level + +- Affects only your user account. +- Stored in your **home directory**. + +**Paths:** + +- **macOS / Linux:** `~/.npmrc` +- **Windows:** `C:\Users\\.npmrc` + +To see the exact path npm uses, run: + +```bash +npm config get userconfig +``` + +You can also list all config and paths with: + +```bash +npm config ls -l +``` + +### Project Level + +- Affects only the project in that folder. +- Stored in the **project root**, next to `package.json`. + +**Example layout:** + +``` +my-project/ + package.json + .npmrc +``` + +Project-level `.npmrc` files are very common because they keep configuration versioned and shared with the team (excluding secrets). + +## How to Create a .npmrc File Manually + +### Step 1: Choose the Location + +Decide between **user level** (all your projects) or **project level** (this repo only). For project level, open your project root in a terminal or editor. + +### Step 2: Create the File + +Create a new file named exactly **`.npmrc`** with no extra extension. + +**On macOS or Linux:** + +```bash +touch .npmrc +``` + +**On Windows:** + +- Create a new text file. +- Rename it to `.npmrc`. +- Remove any `.txt` extension (you may need to enable "Show file extensions" in Explorer). + +### Step 3: Add Configuration + +Open `.npmrc` in a text editor and add one setting per line. Example: + +```ini +registry=https://registry.npmjs.org/ +``` + +Save the file. npm will read it automatically on the next command. + +## How to Let npm Create the .npmrc File + +npm can create a user-level `.npmrc` for you when you log in: + +```bash +npm login +``` + +npm will prompt for: + +- Username +- Password +- Email + +After a successful login, npm creates or updates `~/.npmrc` (or your platform's user config path) and stores an authentication token. This is useful when you don't want to manage tokens manually for the default registry. + +## Common .npmrc Settings Explained + +### Registry URL + +Tells npm where to download packages: + +```ini +registry=https://registry.npmjs.org/ +``` + +### Authentication Token + +Used for private or authenticated registries. **Never commit real tokens to a public repo.** + +```ini +//registry.npmjs.org/:_authToken=YOUR_TOKEN +``` + +Prefer environment variables in CI and locally: + +```ini +//registry.npmjs.org/:_authToken=${NPM_TOKEN} +``` + +npm expands `${NPM_TOKEN}` from the environment. See the [npm blog on private modules](https://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules) and the [npmrc documentation](https://docs.npmjs.com/files/npmrc). + +### Scoped Packages + +Use a custom registry only for a specific scope: + +```ini +@mycompany:registry=https://registry.example.com/ +``` + +Packages whose name starts with `@mycompany` will use that registry. + +### Save Exact Versions + +Control how versions are written to `package.json` (e.g. exact version vs ranges): + +```ini +save-exact=true +``` + +Or with the legacy prefix style: + +```ini +save-prefix='~' +``` + +## How npm Reads Multiple .npmrc Files + +npm can load several `.npmrc` files. Precedence order (highest wins): + +1. **Project level** (current directory, then ancestors) +2. **User level** (`~/.npmrc` or `npm config get userconfig`) +3. **Global level** (system config) + +If the same key appears in more than one file, the more specific level overrides the more general one. That gives you global defaults with the option to override per project. + +## Best Practices for Using .npmrc Files + +### Do Not Commit Secrets + +Never commit authentication tokens or passwords to a public (or shared) repository. If `.npmrc` contains secrets, add it to `.gitignore` and use a `.npmrc.example` with placeholder values. + +### Use Environment Variables + +Prefer environment variables for tokens so that: + +- Secrets aren't in the repo. +- CI/CD can inject different tokens per environment. + +Example: + +```ini +//registry.example.com/:_authToken=${NPM_TOKEN} +``` + +### Keep It Simple + +Only add settings you actually need. A minimal `.npmrc` is easier to understand and maintain. + +### Document Your Setup + +If you work in a team, document why `.npmrc` exists (e.g. custom registry, scope) and how to obtain any required tokens or env vars. + +## Common Problems and How to Fix Them + +### npm Seems to Ignore .npmrc + +Check which config npm is using: + +```bash +npm config ls -l +``` + +Confirm the **userconfig** path and that your file is at the expected location. For project-level config, ensure the file is in the project root (same directory as `package.json`). + +### Permission Errors + +Ensure the file is readable (and writable if npm needs to update it) by your user. On Unix-like systems, `chmod` and ownership can affect this. + +### Wrong Registry Used + +If the wrong registry is used, another `.npmrc` may be overriding your setting. Check project, user, and global config with `npm config ls -l` and fix or remove the overriding value. + +### 404 for a Private Package + +If you get "404 Not found" for a scoped or private package, verify: + +- The scope and registry in `.npmrc` match the package name. +- Your token has access to that package/scope. +- The token is not expired. + +## Why .npmrc Matters in Real Projects + +In real Node.js projects, `.npmrc` helps teams share the same registry and auth setup, avoid "works on my machine" issues, and keep private package access secure. Whether you work on a small app or a large monorepo, understanding and using `.npmrc` makes installs and CI more reliable. + +## Conclusion + +The `.npmrc` file is a small but powerful way to control how npm behaves. It helps you manage registries, authentication, and project settings in a consistent and secure way. Adding and maintaining a `.npmrc` file is simple; knowing where and how to use it improves your Node.js workflow and reduces common install and auth errors. + +For more community tips and troubleshooting, see [How can I add a .npmrc file?](https://stackoverflow.com/questions/42877722/how-can-i-add-a-npmrc-file) on Stack Overflow. With a correctly set up `.npmrc`, npm will handle configuration in the background and make your projects easier to manage. diff --git a/public/static/images/nodejs-npmrc.jpg b/public/static/images/nodejs-npmrc.jpg new file mode 100644 index 0000000000..4608a1dde9 Binary files /dev/null and b/public/static/images/nodejs-npmrc.jpg differ