Check Project Name Availability

Use caniname and a custom check to find a project name free everywhere.

Introduction

30 Second Summary

Finding the right project name is hard enough before you discover that someone already claimed it on the service you need. Checking each site by hand turns a quick naming decision into a trail of tabs.

In this project, you will use caniname to compare candidate names across npm and Netlify. You will extend the tool with an availability check for another service.

What You'll Build

Your final shortlist will appear in a JSON report with availability results from every built-in source plus your custom check.

By the end of this project, you'll have:

  • A side-by-side name check that shows which candidate names are available across each built-in source.
  • A reusable JSON report you can open alongside your project notes when choosing a final name.
  • A working custom service check that appears automatically when you run your local copy of caniname.
  • Secret Mission: An optional challenge to push your skills further.

Are there any prerequisites?

You need Node.js plus access to the npx command.

Before We Start

Caniname runs through Node.js. Your computer needs this runtime before it can check a project name.

The later source checkout needs Git. You also need Visual Studio Code for reading the check files.

In this step, get ready to:
  • Install Node.js with its npm command-line tools.
  • Prepare Git plus a code editor for the source checkout.
  • Confirm each tool works from a terminal with internet access.
Install Node.js and npm

Node.js runs the CLI on your computer. Its installer also includes npm plus the npx command.

macOS

  • Press Cmd+Space to open macOS search.
  • Type Terminal and press Enter.

Windows

  • Press the Windows key to open Windows search.
  • Type PowerShell and press Enter.
  • Check whether Node.js plus npm are available by running:
node --version
npm --version

What does this check prove?

  • The first command asks Node.js to print its installed version.
  • The second command asks npm to print its installed version.

✔️ I see two version numbers

Good start. Node.js plus npm are ready to run command-line packages.

ⓧ Node.js is not available

Install the Long Term Support release for your operating system. This release is labelled LTS on the official download page.

macOS

  • Open the official Node.js download page.
  • Choose the download labelled LTS for macOS.
  • Open the downloaded installer.
  • Follow the installer prompts using the default options.
  • Close Terminal after the installation finishes.
  • Press Cmd+Space to open macOS search.
  • Type Terminal and press Enter.
  • Confirm the installation by running:
node --version
npm --version
What should you see?

You should see one version number for Node.js. A second version number confirms npm was installed with it.

Windows

  • Open the official Node.js download page.
  • Choose the download labelled LTS for Windows.
  • Open the downloaded installer.
  • Follow the installer prompts using the default options.
  • Close PowerShell after the installation finishes.
  • Press the Windows key to open Windows search.
  • Type PowerShell and press Enter.
  • Confirm the installation by running:
node --version
npm --version
What should you see?

You should see one version number for Node.js. A second version number confirms npm was installed with it.

Install Git and Visual Studio Code

Git downloads the caniname source code later in the project. Visual Studio Code gives you an editor for inspecting its checks folder.

  • Check whether Git is available in the terminal from earlier by running:
git --version

What does this check prove?

Git prints its installed version when the command is available. That output confirms the terminal can find Git.

✔️ I see a Git version

Git is ready for the source checkout later in the project.

ⓧ Git is not available

macOS

Expect an installation dialog

The next command starts the macOS Command Line Tools installer. Your computer opens a system dialog for the installation.

  • Start the Git installation by running:
xcode-select --install
What does this command do?

The command requests Apple's Command Line Tools package. Git is included in that package.

  • Complete the installation in the system dialog.
  • Return to Terminal after the installation finishes.
  • Confirm Git is available by running:
git --version
What should you see?

You should see a line containing the installed Git version.

Windows

  • Open the official Git for Windows installation page.
  • Choose the installer that matches your computer.
  • Run the downloaded installer.
  • Approve the system permission request if it appears.
  • Keep the default installer options.
  • Close PowerShell after the installation finishes.
  • Press the Windows key to open Windows search.
  • Type PowerShell and press Enter.
  • Confirm Git is available by running:
git --version
What should you see?

You should see a line containing the installed Git version.

A code editor keeps the source files readable when you add your own check. Install Visual Studio Code before opening its built-in terminal.

macOS

  • Open the official Visual Studio Code download page.
  • Download the macOS .dmg for your computer.
  • Open the downloaded .dmg file.
  • Drag Visual Studio Code into the Applications folder.

Windows

  • Open the official Visual Studio Code download page.
  • Download the User Installer for your computer.
  • Run the downloaded installer.
  • Follow the installer prompts using the default options.
  • Press Cmd+Space on macOS or the Windows key on Windows to open system search.
  • Type Visual Studio Code and press Enter.

You should see the Visual Studio Code editor window. Your code editor is ready for the later source changes.

Verify the toolchain in Visual Studio Code

The integrated terminal runs commands inside your editor. One final check confirms the three tools are available from the place where you work.

  • Click View in the Visual Studio Code menu bar.
  • Click Terminal to open the integrated terminal.

Before you run the final check, how many version lines do you expect before the network result?

  • Confirm the tool versions plus npm registry access by running:
node --version
npm --version
git --version
npm ping

What should you see?

  • The first line shows the installed Node.js version.
  • The second line shows the installed npm version.
  • The third line shows the installed Git version.
  • The final check reports that the configured npm registry responded.

That is your development toolchain ready. Visual Studio Code can now reach Node.js plus npm plus Git from its terminal.

Missing a version or registry response?

  • Restart Visual Studio Code so its terminal loads the paths added by each installer.
  • Confirm you completed the Node.js installer before checking npm.
  • Confirm the Git installer finished before reopening the terminal.

Still stuck? Help me diagnose my development tool setup.

Your terminal is ready for the naming checks. Next, you'll compare a name you know is taken with one you invent.

Compare Taken and Free Names

A promising project name can still collide with a package or hosted site that already exists.

In this step, you'll use caniname to compare a known-taken candidate with a made-up candidate. Running them in one batch makes the contrast easy to spot.

In this step, get ready to:
  • Run caniname against two candidate names in one batch.
  • Compare the taken result with the available results from every configured source.
Run both names in one batch

A useful baseline includes one result whose status you already know. Using two candidates in one command gives every configured check the same conditions.

  • Switch back to the terminal from earlier.
  • Follow any terminal prompt to approve downloading caniname.

Before you run this, consider which candidate you expect to produce a taken result.

  • Compare both candidates in one batch by running this command:
npx caniname react nextwork-namecheck-2026

What does this command do?

  • The npx command runs the published caniname package directly.
  • Caniname applies every registered source check to react plus nextwork-namecheck-2026.
  • An exit code of 1 signals that a name is taken or a source returned an error.
  • Find the result group for react.
  • Confirm that npm reports react as taken.
  • Find the result group for nextwork-namecheck-2026.
  • Confirm that every configured source reports nextwork-namecheck-2026 as available.

That's your baseline working. The terminal now shows an occupied name beside an available one.

Missing one of the result groups?

  • Check that the terminal still has internet access.
  • Review any package download prompt that is still waiting for approval.
  • Confirm that the command contains react plus nextwork-namecheck-2026 separated by a space.

Still stuck? Help me diagnose why caniname did not show both candidate result groups.

Confirm the comparison

The comparison is complete when one command produces a result group for each candidate. Every configured source should appear under both names.

  • Keep the completed caniname output visible in the terminal.
  • Check that both candidate names belong to the same command run.
  • Check that each candidate has a status from every configured source.

✔️ Awesome, I've got everything!

Great. Your terminal contains availability results for both candidate names from the same caniname run.

ⓧ I'd like to double check the full code

  • Compare your terminal history with this reference command:
npx caniname react nextwork-namecheck-2026

The output should record every configured source's taken or available result for both names.

You can now recognise both availability states in one terminal run. Next up, you'll turn a shortlist into a report you can open outside the terminal.

Save a JSON Name Report

Your first caniname run put two names side by side in the terminal. Once that output scrolls away, it becomes difficult to reuse during your final naming decision.

A JSON report gives your shortlist a durable record. In this step, you'll check three candidate names in one run.

You'll save every built-in source result in candidate-names-report.json.

In this step, get ready to:
  • Check three candidate names in one caniname run.
  • Save the JSON output in a local report file.
  • Confirm every built-in source appears in the report.
Capture structured results

The --json option changes caniname's terminal results into structured data. Shell redirection writes that data directly into a file on your Desktop.

  • Save the three-name report on your Desktop by running this command:
npx caniname nextwork-namecheck-2026-a nextwork-namecheck-2026-b nextwork-namecheck-2026-c --json > ~/Desktop/candidate-names-report.json

What does this command do?

  • The npx command runs caniname without a global installation.
  • The three candidate arguments make caniname check every name in the same run.
  • The --json option requests machine-readable results.
  • The final part writes those results into candidate-names-report.json on your Desktop.

Before you check, do you expect one report file or three separate files? Hold that prediction.

  • Confirm that the report file exists by running this command:
ls ~/Desktop/candidate-names-report.json

What does this check prove?

The ls command lists the report at its exact Desktop path. Seeing the path confirms that the redirection created one file for the complete three-name run.

You should see candidate-names-report.json in the output.

That's the reusable record in place. Your shortlist now survives beyond this terminal session.

Report file missing or empty?

  • Compare the filename in your command with candidate-names-report.json.
  • Confirm that your terminal still has internet access.
  • Rerun the report command if the file is empty.

Help me diagnose why my caniname JSON report is missing or empty.

Inspect the saved report

A saved report only helps if you can read it outside the terminal. Opening the file proves that the redirection captured valid JSON.

Before you open the report, how do you think one run with three names will be organised? Hold that picture in mind.

  • Return to the code editor from earlier.
  • Use its file picker to select candidate-names-report.json from your Desktop.
  • Scroll through the report to review all three candidate sections.

You should see nextwork-namecheck-2026-a, nextwork-namecheck-2026-b, and nextwork-namecheck-2026-c in the report.

Each candidate should include an availability result from every built-in source.

You have turned a temporary terminal check into evidence you can use for the final decision.

Report not opening correctly?

  • Confirm that you selected candidate-names-report.json from your Desktop.
  • Return to the file check above if your editor displays an empty report.

Help me inspect a caniname report that does not display valid JSON.

Your shortlist now has a saved JSON record covering every built-in source. Next, you'll get caniname's source code and inspect the folder that makes its checks pluggable.

Inspect the Source Checks

Your JSON report now captures three names across every built-in source. The next goal is to find the code behind each source.

A local Git checkout gives you the full caniname repository. You’ll inspect its src/checks/ folder to see how each service maps to a separate file.

In this step, get ready to:
  • Clone the official caniname source repository to your Desktop.
  • Open the source checkout in your code editor.
  • Confirm that the original service-check files are visible.
Work from the official repository

The published package hides the source layout behind one command. The official GitHub repository exposes the files you need for the custom check.

  • Create the source checkout on your Desktop by running these commands:
cd ~/Desktop
git clone https://github.com/bramus/caniname caniname

What do these commands do?

The first command keeps the checkout in a predictable place on your Desktop. Git then downloads the official repository into a new caniname folder.

  • Confirm the downloaded source folder by running these commands:
cd ~/Desktop/caniname
ls

What should I see?

The second command lists the repository’s top-level contents. You should see a src entry among the downloaded files.

Can’t see the source folder?

  • Check that the clone command finished before you ran the verification commands.
  • Check whether a different caniname folder already existed on your Desktop.
  • Confirm that your terminal has internet access to reach GitHub.

Still stuck? Help me diagnose why the caniname repository did not clone to my Desktop.

Inspect the checks folder

Each supported service has its own check file inside src/checks/. This layout gives you a clear example to study before you add anything.

  • Return to the code editor from earlier.
  • Choose its folder-opening option from the top menu.
  • Select the caniname folder from your Desktop.
  • Confirm the folder selection.
  • Expand src in the editor’s file sidebar.

Before you expand checks, do you expect one shared file or a separate file for each service?

  • Expand checks inside the open src folder.

You’ll see separate .js files. Each file represents one built-in service.

You now have a clean baseline. The custom github-username.js check is still absent.

The source checkout is open with its original checks visible. Next, you’ll use one of those files as the starting point for your own service check.

Add a GitHub Username Check

The local source checkout shows that caniname isolates every service in its own check file. That layout gives you a safe pattern for extending the tool without changing the original checks.

In this step, you'll copy one existing check into a new GitHub username check. The custom file will decide availability from whether a candidate's GitHub profile URL exists.

In this step, get ready to:
  • Choose an existing URL-based service check as your pattern.
  • Create github-username.js beside the original check files.
  • Adapt the request logic to report existing usernames as taken.
Choose a matching check pattern

Each existing check follows the interface that caniname expects. A URL-based check gives you the closest starting point because it already turns a candidate name into a web request.

  • Return to the caniname/checks/ folder that is already open in your code editor.
  • Identify an existing check that constructs a candidate-specific URL before testing its response.
  • Select that file as the pattern for your GitHub username check.

Why copy an existing check?

Every check accepts a candidate name. It turns that input into a service-specific request.

The returned availability value gives caniname a common result shape. Copying an existing module preserves that contract.

Create the GitHub check

The copied file supplies the module structure that caniname already understands. You only need to replace the parts that belong to the original service.

  • Duplicate the selected check inside caniname/checks/ with your editor's file-tree copy action.
  • Name the duplicate github-username.js.

You should now see github-username.js beside the original service-check files.

  • Open github-username.js from the checks folder.
  • Replace the copied service metadata with values that identify a GitHub username check.
  • Remove any input rules that only apply to the copied service.

The module should now describe the new GitHub username source while keeping the copied check structure.

  • Replace the copied URL construction with a profile URL that appends the normalized candidate name to https://github.com/.
  • Direct the copied request block to the new GitHub profile URL.

The request should now test the profile for the current candidate name.

How should the availability mapping work?

The check uses the profile URL as evidence. A URL that resolves belongs to an existing username.

A missing profile leaves the candidate username free.

  • Update the availability result so only a missing GitHub profile counts as free.
  • Keep the copied error-handling structure unchanged.

The completed logic now maps an existing profile to taken. It maps a missing profile to free.

  • Save caniname/checks/github-username.js.

Why is no GitHub account required?

The check requests a public profile URL. It does not create a username or change anything on GitHub.

That keeps the check lightweight because it needs no account registration or credentials.

Verify the new check file

Before you inspect the folder, where do you expect the new file to appear relative to the original checks?

  • Return to the open caniname/checks/ folder in your editor's file tree.
  • Confirm that github-username.js appears beside the original check files.
  • Select github-username.js in the file tree.
  • Confirm that its URL construction points to the candidate's GitHub profile.
  • Confirm that a missing profile maps to free.
  • Confirm that an existing profile maps to taken.

Strong work. Your checks folder now contains a GitHub username check beside the original service checks.

✔️ Awesome, I've got everything!

Your saved github-username.js file now targets GitHub profile URLs with the correct availability mapping.

ⓧ I'd like to double check the full code

Compare the complete github-username.js file against this behavior checklist:

  • The service metadata identifies the module as a GitHub username check.
  • The request URL starts with https://github.com/ and ends with the normalized candidate name.
  • The request tests the constructed GitHub profile URL.
  • The availability result is free only when the profile is missing.
  • The copied module export structure remains intact.

Don't see the file beside the originals?

  • Check that the duplicate is saved inside caniname/checks/.
  • Check that the filename is exactly github-username.js.

Still stuck? Help me find why my custom caniname check is missing from the checks folder.

Your custom module is in place. Next up, you'll run caniname locally to prove that the new check is discovered automatically.

Verify the Local Check

Your custom GitHub username check now sits beside the original checks. A file in the folder only proves that the edit exists.

This step runs the local caniname checkout to prove that it discovers the new check. You will see the GitHub username result beside the built-in sources without changing a central registry.

In this step, get ready to:
  • Run the caniname checkout from its own folder.
  • Confirm the GitHub username result appears alongside the built-in results.
Run the local checkout

A local run uses the source inside your caniname/ checkout. This gives your custom check a direct test before any publishing step.

  • Switch back to the terminal from earlier.
  • Place the terminal inside the open caniname/ checkout using your code editor's terminal control.
  • Confirm that the terminal prompt points to the caniname/ folder.

Before you run the local checkout, predict whether the output will list only the built-in sources or include the GitHub username check.

  • Test two candidate names with the local checkout by running this command:
./bin/caniname.js formula-input calc-input

What does this command prove?

  • The ./bin/caniname.js launcher runs the source from your local checkout.
  • The formula-input and calc-input values give every discovered check two candidate names to test.
  • A GitHub username result proves that the launcher found your new check file.

You will see one result group for each candidate name. Each group includes the GitHub username check beside the built-in source checks.

Local command did not run?

  • Confirm that the terminal prompt points to caniname/. The relative launcher path starts from that folder.
  • Confirm that caniname/checks/github-username.js remains beside the original check files.
  • Check the terminal's internet connection if a source cannot return an availability status.

Still stuck? Help me debug the local caniname run.

Confirm automatic discovery

Automatic discovery lets each check live in its own file. The successful result row proves that caniname loaded your file without a registration step.

  • Find the GitHub username row under the formula-input result group.
  • Find the same GitHub username row under the calc-input result group.
  • Compare the GitHub username rows with the built-in source rows.

Before the final check, predict what would prove that the new file was discovered automatically.

  • Review both candidate result groups in the terminal.

You should see the GitHub username check displayed for both candidates. Its position beside the built-in checks confirms that no central list or GitHub account was required.

Why did this work automatically?

caniname discovers check files from its checks folder when the local launcher runs. Adding one file extends the output without changing a separate registry.

That closes the loop. Your custom check now runs as a first-class source from a single file.

Your local checkout now includes the GitHub username result in every availability run. Next, you will test your final shortlist and choose a name that is free across every source.

Choose Your Final Name

Your custom GitHub username check now appears beside caniname's built-in sources. The last decision is choosing one name that clears the full set.

The earlier JSON report predates your extra check. A fresh local report lets you choose the name marked free across every source.

In this step, get ready to:
  • Generate a local report for all three shortlisted names.
  • Confirm that the report includes every built-in source plus the GitHub username check.
  • Select the name that is free across every source.
Generate the final shortlist report

Your earlier report contains results from the built-in checks. This final report must come from the local checkout so the automatically discovered GitHub username check is included.

Before you run the shortlist, do you expect the saved report to contain a GitHub username result for all three names?

  • Return to the terminal you used to run caniname locally.
  • Generate final-shortlist-report.json from the local checkout by running this command:
./bin/caniname.js nextwork-namecheck-2026-a nextwork-namecheck-2026-b nextwork-namecheck-2026-c --json > final-shortlist-report.json

What does this command do?

  • The local ./bin/caniname.js executable runs the checkout that contains your custom check.
  • The three candidate arguments send your complete shortlist through the same run.
  • The --json flag formats every result as structured JSON.
  • The > operator saves that output in final-shortlist-report.json.
  • Return to the code editor from earlier.
  • Select final-shortlist-report.json from the file sidebar.
  • Confirm that the report contains result objects for all three shortlisted names.
  • Confirm that each candidate includes the GitHub username check beside the built-in sources.

You'll see a complete result set for nextwork-namecheck-2026-a, nextwork-namecheck-2026-b, and nextwork-namecheck-2026-c.

Missing the report or GitHub result?

  • Make sure you returned to the terminal that is running from the local caniname checkout.
  • Check that caniname/checks/github-username.js is still beside the original check files.
  • Refresh the code editor's file sidebar if final-shortlist-report.json does not appear.

Still stuck? Help me find why my local caniname JSON report is missing the GitHub username check.

Select the all-free name

Each source result contains an available value. A candidate qualifies when every one of those values is true.

  • Review every source result under nextwork-namecheck-2026-a.
  • Review every source result under nextwork-namecheck-2026-b.
  • Review every source result under nextwork-namecheck-2026-c.
  • Identify the candidate whose every available value is true.
  • Record your final choice here: your selected shortlist name.

Before your final check, do you expect your chosen candidate to contain any unavailable result?

  • Return to the result block for your selected shortlist name.
  • Confirm that every available field in that result block is true.

You'll see true for every source under your chosen candidate. You now have a final name backed by one complete report.

Secret mission

Run a Launch-Day Name Audit

Turn your saved availability results into a launch gate for your selected project name. Compare the reports to prove that your custom username check expanded the tool's coverage. Finish with a rule that tells you when the name is ready to publish.

Clean Up Your Resources

Clean Up Your Resources

Everything this project created lives on your computer. There are no ongoing charges. Choose the cleanup option that fits what you want to do next.

Resources you used:

  • The local source checkout in caniname/. This folder includes the custom caniname/checks/github-username.js check.
  • The built-in availability results in candidate-names-report.json.
  • The complete shortlist results in final-shortlist-report.json.

Keep everything running

No action is needed. Choose this option if you want to reuse the reports or continue improving your custom check.

  • Keep final-shortlist-report.json with your project notes as evidence for your naming decision.
  • Keep caniname/ if you want to extend caniname/checks/github-username.js.
  • Keep candidate-names-report.json if you want to compare the built-in results with the extended report.

The completed checks leave no background service running. Your local files create no ongoing cost.

Pause - I'll come back to this later

Shut down your working session while preserving the source checkout. Your two reports remain ready for the next naming session.

  • Save caniname/checks/github-username.js in the code editor from earlier.
  • Close the code editor window containing caniname/.
  • Close the terminal window from earlier.
  • Keep candidate-names-report.json with your local project files.
  • Keep final-shortlist-report.json with your project notes.

Your checkout retains the verified custom check. You can continue without rebuilding it.

Delete - I don't want to use this again

Deleting the folder and reports is permanent. Your existing development tools stay installed.

Keep final-shortlist-report.json if you still want a record of why you selected your final name.

macOS

Finder can locate each local artifact before you move it to Trash. Match the source checkout by checking for your custom file.

  • Close the code editor from earlier.
  • Close the terminal window from earlier.
  • Search Finder for caniname.
  • Move the caniname/ result containing checks/github-username.js to Trash.
  • Search Finder for candidate-names-report.json.
  • Move candidate-names-report.json to Trash.
  • Search Finder for final-shortlist-report.json.
  • Move final-shortlist-report.json to Trash.

The three artifacts are now staged for removal. Emptying Trash completes the cleanup.

  • Empty Trash.
  • Search Finder again for caniname.
  • Search Finder again for candidate-names-report.json.
  • Search Finder again for final-shortlist-report.json.

You should see no matching source checkout.

You should also see no matching JSON reports. Your local project artifacts are now removed.

Windows

File Explorer can locate each local artifact before you move it to the Recycle Bin. Match the source checkout by checking for your custom file.

  • Close the code editor from earlier.
  • Close the terminal window from earlier.
  • Search File Explorer for caniname.
  • Move the caniname/ result containing checks/github-username.js to the Recycle Bin.
  • Search File Explorer for candidate-names-report.json.
  • Move candidate-names-report.json to the Recycle Bin.
  • Search File Explorer for final-shortlist-report.json.
  • Move final-shortlist-report.json to the Recycle Bin.

The three artifacts are now staged for removal. Emptying the Recycle Bin completes the cleanup.

  • Empty the Recycle Bin.
  • Search File Explorer again for caniname.
  • Search File Explorer again for candidate-names-report.json.
  • Search File Explorer again for final-shortlist-report.json.

You should see no matching source checkout.

You should also see no matching JSON reports. Your local project artifacts are now removed.

Nice Work!

Nice Work!

You did it! Your custom GitHub username check now gives caniname one more source to test.

You also have a saved report that identifies the shortlist name available across every configured source.

You've learned how to:

  • Compare a known taken name with an invented candidate. The side-by-side results showed how each source reports availability.
  • Generate a machine-readable JSON report with --json. You used final-shortlist-report.json to identify the candidate that was free across every source.
  • Extend the pluggable check system with caniname/checks/github-username.js. Your local run confirmed that caniname discovered the new check automatically.
  • Complete the optional Secret Mission to push your naming workflow further.

Ready to quiz yourself?