DEV Community: Donato Riccio

Create your custom npm template package

Donato Riccio — Mon, 10 Mar 2025 19:41:58 +0000

a.k.a what `npm create vite@latest` does

What we want
Before you continue
- Try the package
The easiest way (template repository)
The npm create way
- The npm create command
- Package requirements
  - main / exports
  - bin
- A really basic package
  - A simple console.log
  - Make the package available globally in your local machine
- How to manage a more complex scaffolding
A simple scaffolding package
- Create a new project
A crossroad
One package, many files
One package, many repos
- A new old repo
- How to interact with the user and install the starter kit
Conclusion
Resources

What we want

We want custom scaffolding to reduce the time needed to start a new project.
Just think about it: how often do you take the same three, four, or five steps to start a project?
Let's use Vue as an example:

install Vue
select maybe the extra packages (Vitest, Vue Router, Pinia)
add Bootstrap (or Tailwind)
add Sass
add Vuex (if you don't want Pinia)
add the simple state management (if you don't want Vuex)
remove unwanted components
add some basic components (i.e. HomePage for Vue Router)
setup Vue Router
and so on...

Instead of repeating all these steps every time, we want a way to have all of them already done on any new project!
Even more: we want the ability to keep our scaffolding updated in time.

How can we do this?

Before you continue

This tutorial is not a step-by-step guide on how to achieve the desired result. Is more of a: we can do things this way, it's possible and not so hard.
The code is publicly available on GitHub and also are the npm packages. Even more: try the packages before you dive into the tutorial.

See if this way of doing things is what you are looking for and only in this case keep reading the tutorial.
Just remember this is not a tutorial on how to do everything. I firmly believe that in some cases is better to learn things "the hard way" rather than have everything handed to you.

Try to make things work, struggle with Node errors, bash your head against the monitor, and close the day with at least a 1% of new things learned.

Try the package

Run this command to install a new VueJS customized template for your project:

npm create @ricciodev/templar@latest

The easiest way (template repository)

One way to achieve the desired result is to create a GitHub repository and mark that repository as a template repository.

We can do this from the tab Settings, right under the repository name.

Now we can create a new repository on GitHub from this template repository. This means the new repository will have all the files included in the template, right from the start.

This is the easiest way to have a basic scaffolding ready to use.
The pros are: easy to do, and easy to maintain/update.
The cons are: if we need more than a couple of different scaffoldings, it becomes a bit hard to manage.

Of course, we can push things further!

NOTE
We will come back to this method later.

The `npm create` way

aka what Vite does

We can create a npm package with the sole purpose of generating a project already structured with all the files and dependencies we need.

Vite do this. Vue does this. Astro does this, and so on... the point being: that we already used this approach.
Now is the time to make our own package!

Before we start, we'll need just a bit of context.

The npm create command

The npm create <package-spec> command is only an alias for npm init <package-spec>.
All the information we need is available in the npm documentation

To sum it up we quote the first paragraph of the npm init documentation page:

npm init <initializer> can be used to set up a new or existing npm package.
initializer in this case is an npm package named create-<initializer>, which will be installed by npm-exec, and then have its main bin executed -- presumably creating or updating package.json and running any other initialization-related operations.

This means our package name will be prefixed with create-.
I.E. create-scaffolding-vue, create-custom-react or to make everything even more organized we could publish our package under a scope to avoid naming conflicts (@myorganization/create-react.)

Package requirements

We need to define some options in the package.json file.

main / exports

First, we set the entry point using the main key. The value will be the path to our main file (usually index.js.)
Later in this tutorial, we will drop main and use the exports field.

bin

We also want to define the bin key pointing to our executable file. For our package, we could use something like this:

{
  "bin": {
    "create-mypackage-name": "./index.js"
  }
}

A really basic package

To start we need to initialize a project using the familiar npm init command.
This will create the basic scaffold for our package and we'll be able to set the requirements we saw in the previous step.

NOTE
If we want to create a scoped package now is the time to make it known to npm by adding our organization name before the package name.
I.E.
@myorg/create-mypackage-name instead of create-mypackage-name

NOTE
When creating a scoped package NPM will default the package to private visibility. To publish the package as public we need to use npm publish --access public.
More on this topic can be found in the notes at the end of this article.

Once the init procedure is done, let's add a new file called index.js (or main.js, or whatever your default naming convention is).
Then we meet the previous requirement: to define the main and the bin keys in package.json.

Both keys need to be defined at the root level of your package.json.
Let's point main to the file we just created:

{
    "main": "./index.js"
}

Then we need to define the bin property pointing to the main executable file of our package.
The files defined here will be installed by npm into the PATH and be available to the package and the user.

The bin key is just a map of the command name to the local file name.

As per the official documentation, if we have only a single executable, and its name should be the name of the package, we could just use a string as the value for bin:

{
    "bin": "./index.js"
}

If we want to be more verbose or we think we'll need to add more executables in the future, we can provide an object instead of a string, with a key named like our package (without the @org prefix).

{
    "bin": {
        "create-mypackage-name": "./index.js"
    }
}

Both these examples are equivalent in our context.

A simple `console.log`

In our index.js add the following code:

#!/usr/bin/env node
console.log("Hello World!");

NOTE
Please make sure that the file referenced in bin starts with #!/usr/bin/env node, otherwise the scripts won't be executed by node!

Make the package available globally on your local machine

We don't need to publish our package to test it.
Executing the npm link command inside the root of our project will make our local package available globally in our system.

Next, we need to create a new directory in another path (i.e. C:\test) and execute the command npm link create-mypackage-name or npm link @myorg/create-mypackage-name if you created a scoped package.
Now our package will be available in the current directory. Yay!

To be sure everything works as expected we need to type the following command in the terminal (from our test folder): npx create-mypackage-name.

NOTE
npx is not a typo, it's the command to run arbitrary commands from local or remote packages.
NPM Docs - npx

The name of the command is the same we defined inside the bin property in package.json.
If we can see the console.log in the terminal, everything is working properly!

NOTE
Now could be a great time to save our code in a repository on GitHub and publish our package.
This way we can try to install it using the npm create @myorg/mypackage-name@latest command and see if everything is ok.
If we see the console.log message after running our command, we are on the right track!

When creating a scoped package NPM will default the package visibility to private. To publish the package as public we need to use npm publish --access public.
More on this topic can be found in the following links.

In this tutorial we won't cover how to publish a package, but the following links will surely help you:
NPM Docs - Creating and publishing unscoped public packages
NPM Docs - Creating and publishing scoped public packages
freeCodeCamp - How to Create and Publish an NPM Package – a Step-by-Step Guide

How to manage a more complex scaffolding

Before we dive into the scaffolding package itself, it is important to understand how to edit the package.json to better organize our code and files.

Imagine we want to create a utility function in a file called toUppercase.js inside the utils folder.

Scaffolding:

index.js
package.json
utils
    toUppercase.js

We want to use the toUppercase.js module inside index.js. To do so we need to import the file at the start of index.js but this will not be sufficient and will throw a ERR_MODULE_NOT_FOUND error.

If you published your package or you made it available globally on your local machine, go ahead and try.

To avoid this error we must update our package.json to export all the files we need and change the import inside index.js to be consistent with our package name.

Inside package.json let's add the exports property:

{
    "exports": {
        ".": "./index.js",
        "./utils/*.js": "./utils/*.js"
    },
}

The official documentation states that:

The "exports" provides a modern alternative to "main" allowing multiple entry points to be defined, conditional entry resolution support between environments, and preventing any other entry points besides those defined in "exports".

NPM Docs - exports

This means we won't need the main field anymore.
In the exports field we defined:

the default entry point index.js
all other entry points inside the utils folder

In index.js we update our import by self-referencing our package using its name.
From:

import toUppercase from './utils/toUppercase.js';

To:

import toUppercase from '@myorg/mypackage-name/utils/toUppercase.js';

This is not a necessary step and only works if we define the exports inside package.json.

Since we defined the property in exports with the .js extension, we must remember to explicitly state the extension when importing our modules.

This will throw an error:

import toUppercase from '@myorg/mypackage-name/utils/toUppercase'; // <-- NO EXTENSION

This will work:

import toUppercase from '@myorg/mypackage-name/utils/toUppercase.js'; // <-- WITH EXTENSION

NOTE
If we already published our package we need to update its patch value and publish it again.
npm version patch will update the version (i.e. from 0.0.1 to 0.0.2).
npm publish will publish the updated version of the package, so that we can install it using npm create @myorg/mypackage-name@latest or npm create @myorg/mypackage-name@0.0.2

We can still test the package locally using the npm link command as before.

A simple scaffolding package

Now is the time to create our custom scaffolding package to bootstrap our projects!
We need to take a couple of minutes to think about how we want your projects to be developed:

Which framework do we want to use?
- I.E. React? Vue? Astro?
What are the packages we use most often?
- I.E. For Vue I find myself always installing Bootstrap, Sass, Vue Router, and Make JS Component
What are some common components or plugins that we always include in our project?
- I.E. Header, Footer, Navigation, a simple state manager, some views...

Create a new project

When we have a clear idea of what we need the following step is to create this project step-by-step, as we did until today.
We create everything we need and nothing more. We do not want to add specific details to this project.

A crossroad

At this moment we are at a crossroads and in front of us have two ways to accomplish the same thing.

One will allow us to have everything in a single package, easy to maintain but it'll need a bit more tweaks to really shine (we won't cover these details right now).
It needs a bit of knowledge of NodeJS and JS in order to be developed and maintained. Other than that it's still a nice way to pack everything up.

The second way leverage NodeJS methods for executing commands, but requires us to create as many repositories as we need scaffolding variations.
On the other hand, this makes updating the scaffolding really easy, and doesn't need to make changes and update the main package in order to have those updates available for us and our users.
We need to execute one command using NodeJS execSync but the whole process is faster and the starter kits are easy to maintain.

Let's explore how every single method works.

NOTE
I will not, at this moment, focus on the meaning of single lines of code.
I will probably make a new tutorial dedicated to some of the functions used in the following parts.

One package, many files

First way, ready to go!

Pros:

single package to maintain
with a bit of NodeJS and NPM knowledge it could really shine
everything is in a single place
Vite also does things this way

Cons:

we need to copy/paste the files from a skeleton project
if we don't want to copy/paste we need to better understand how git, NodeJS, and NPM work
for every change in our scaffolding we need to publish a new version of the package

Update the scaffolding of the npm package

Back to our package!
We want to create a template directory, and if we want to be future proof we should also make a specific framework/library/tech directory.
In this example, we will create a vue directory.

This is the current scaffolding of our npm package:

index.js
package.json
utils
    toUppercase.js
template
    vue

Inside the vue folder we will copy everything from the project we created in the previous step.

NOTE
Of course we will not copy the node_modules folder and neither the package-lock.json file.
A basic skeleton of a fresh new project will be enough.

How to interact with the user and copy the scaffolding files

NOTE
As mentioned before this part will be more of a copy/paste for now. If you are interested I will make a future article focusing on some of the methods and packages I used.

We need to ask our users about the project our package will create.
To accomplish this task we need the inquirer package (the following code is referencing the linked version, but feel free to use the new version of inquirer and edit the code example).

After installing inquirer we need to update our main entry point, index.js:

#!/usr/bin/env node

import toUppercase from '@myorg/mypackage-name/utils/toUppercase.js';
import inquirer from 'inquirer';

(async () => inquirer
    .prompt([
        {
            type: "input",
            name: "projectName",
            message: "Enter your project name",
            default: "obi-wan-kenobi"
        }
    ])
    .then((answers) => {
        console.log(toUppercase(answers.projectName));
    })
    .catch((error) => {
        if (error.isTtyError) {
            // Prompt couldn't be rendered in the current environment
            console.error("Cannot render the prompt...");
        } else {
            console.error(error.message);
        }
    }))();

Running our project (locally or after publishing a new version and installing it again) will give us a nice prompt inside our terminal, asking for the name of our shiny new project.

Perfection!

Instead of printing the project name all in uppercase inside the console, we will copy the files and folders from template/vue inside the current project directory.

We must create a new file inside the utils folder: createProject.js.
Inside this file we will add two functions:

a init function that will start the whole process
a copyTemplateFilesAndFolders function that will recursively copy all the files and folders from the template directory

import fs from 'fs/promises';
import { fileURLToPath } from "node:url";
import path from "node:path";
import chalk from 'chalk';

export const copyTemplateFilesAndFolders = async (source, destination, projectName) => {
    const filesAndFolders = await fs.readdir(source);

    for (const entry of filesAndFolders) {

        const currentSource = path.join(source, entry);
        const currentDestination = path.join(destination, entry);

        const stat = await fs.lstat(currentSource);

        if (stat.isDirectory()) {

            await fs.mkdir(currentDestination);
            await copyTemplateFilesAndFolders(currentSource, currentDestination);

        } else {

            // If the file is package.json we replace the default name with the one provided by the user
            if (/package.json/.test(currentSource)) {
                const currentPackageJson = await fs.readFile(currentSource, 'utf8');
                const newFileContent = currentPackageJson.replace(/custom-scaffolding/g, projectName);

                await fs.writeFile(currentDestination, newFileContent, 'utf8');
            } else {
                await fs.copyFile(currentSource, currentDestination);
            }

        }
    }
};

export const init = async (projectName) => {

    const destination = path.join(process.cwd(), projectName);

    const source = path.resolve(
        path.dirname(fileURLToPath(import.meta.url)),
        "../template/vue"
    );

    try {
        console.log('📑  Copying files...');

        await fs.mkdir(destination);
        await copyTemplateFilesAndFolders(source, destination, projectName);

        console.log('📑  Files copied...');
        console.log(chalk.green(`\ncd ${projectName}\nnpm install\nnpm run dev`));
    } catch (error) {
        console.log(error);
    }
};

To make the message more pretty in the terminal we could install chalk.
This is not a mandatory step but a nice one. Of course, if we don't want to use this library it's sufficient to remove all references to it from the previous code.

Just a bit of context before we continue.
The previous code has two functions. The init function receives the project name and with the help of the path module we create a path (of course) pointing to a folder named like the project name we provided, concatenated to our current working folder (this comes from process.cwd()).
The join methods will use the correct path separator based on the OS the package is installed on.

const destination = path.join(process.cwd(), projectName);

With the help of the fs module NodeJS can use the method mkdir to create a new folder:

await fs.mkdir(destination);

We need to resolve the path to our scaffolding files and folders. To do this we will use the resolve method of the path module:

const source = path.resolve(
    path.dirname(fileURLToPath(import.meta.url)),
    "../template/vue"
);

I leave to the official documentation and to your curiosity the explanation for this bit ;)

The copyTemplateFilesAndFolders will be called with three arguments: source (where the template is), destination (the folder just created and named after what we typed in the prompt), projectName (the name of our project).

copyTemplateFilesAndFolders will then copy every single folder and file from the source to the destination. For each folder it will recursively call itself to copy every file from it.

When the function finds the package.json file it will overwrite the default project name with the one we provided.

NOTE
We could also parse the file content as JSON and overwrite the name property using direct access.
We will then re-encode the object as JSON string and write it back to the file.

Now it's a good time to test again our package and see if everything works correctly.
If the test with the local package is showing you index.js instead of executing it, just unlink and re-link the project.

With this step, we are done! Now we can create a new project with everything we want, using a single npm command.

One package, many repos

This is the last method to tackle this problem.

Pros:

it's easier to add a new scaffolding and to keep things up to date
only one single package to update and publish
starter kit repos are easy to maintain

Cons:

you don't really need a npm package to install a git repo, so it's a bit of an extra step

A new old repo

First things first!
Remember the template repository we saw at the start of this tutorial? We are going back to it and will sprinkle a bit of NodeJS and NPM magic dust over it.

How to interact with the user and install the starter kit

As we did for the other version, we need to use inquirer to ask our users (or our future selves) the name of the project and what kit we want to use.

Since we want to be able to define more than one starter kit and we want things to be tidy and clean, we should create a new file inside the utils folder called allowedPackages.js.
This package will define the scope (our GitHub username -- my-github-username), the starter kit (an array of strings), and a method that will create an array of allowed packages (this will come in handy later for security purposes).

Here's the content of the file:

export const scope = 'my-github-username';

export const starterKits = [
    'vue'
];

export function allowedPackages() {
    return starterKits.map(kit => `${scope}/${kit}-starter-kit`);
}

We need to update index.js to import this file and to ask our users which kit they want to install.
Here's the updated index.js:

#!/usr/bin/env node

import { init } from '@myorg/mypackage-name/utils/createProject.js';
import { allowedPackages, starterKits, scope } from '@myorg/mypackage-name/utils/allowedPackages.js';
import inquirer from 'inquirer';

(() => inquirer
    .prompt([
        {
            type: "input",
            name: "projectName",
            message: "Enter your project name",
            default: "obi-wan-kenobi"
        },
        {
            type: "list",
            name: "prefix",
            message: "Select a starter kit",
            choices: [...starterKits]
        }
    ])
    .then((answers) => {
        const requestedPackage = `${scope}/${answers.prefix}-starter-kit`;

        if (!allowedPackages().includes(requestedPackage)) {
            throw new Error("Invalid package");
        }
        
        init(answers.projectName, requestedPackage);
    })
    .catch((error) => {
        if (error.isTtyError) {
            // Prompt couldn't be rendered in the current environment
            console.error("Cannot render the prompt...");
        } else {
            console.error(error.message);
        }
    }))();

We added a new option to our users: what starter kit they want.
Note that we check if the selected package is valid. If not it means the user tried to send some arbitrary value and the script will throw an error and stop the execution.

Of course, the createProject.js module changed as well:

import fs from 'fs/promises';
import path from "node:path";
import chalk from 'chalk';
import { execSync } from 'node:child_process';

const updatePackageJson = async (projectPath, requestedPackage, projectName) => {

    console.log(chalk.gray('Updating package.json...'));

    const packagePath = path.join(projectPath, 'package.json');
    const stat = await fs.lstat(packagePath);

    if (stat.isFile()) {
        const currentPackageJson = await fs.readFile(packagePath, 'utf8');
        const newFileContent = currentPackageJson.replace(requestedPackage, projectName);
        await fs.writeFile(packagePath, newFileContent, 'utf8');
    }
}

const removeGitFolder = async (projectPath) => {

    console.log(chalk.gray('Removing .git folder...'));

    const gitFolderPath = path.join(projectPath, '.git');
    const stat = await fs.lstat(gitFolderPath);

    if (stat.isDirectory()) {
        await fs.rm(gitFolderPath, {
            recursive: true
        });
    }
}

export const init = async (projectName, requestedPackage) => {

    try {

        const currentDir = process.cwd();
        const destination = path.join(currentDir, projectName);
        const fullURL = `https://github.com/${requestedPackage}.git`

        console.log(chalk.gray('📑  Copying files...'));

        await fs.mkdir(destination);
        execSync(`git clone --depth 1 ${fullURL} .`, { stdio: "inherit", cwd: destination });

        console.log(chalk.gray('📑  Files copied...'));

        await removeGitFolder(destination);
        await updatePackageJson(destination, requestedPackage, projectName);

        console.log(chalk.green(`\ncd ${projectName}\nnpm install\nnpm run dev`));
    } catch (error) {
        console.log(chalk.red(error));
    }
};

On this one, we have simplified a couple of things.
The copyTemplateFilesAndFolders doesn't exist anymore. This time we need two functions to update the default package.json we are getting from the starter kit repo and a function to remove the .git folder from the cloned repo.

The init function will use execSync to execute the git clone command for our starter kit repo:

git clone --depth 1 ${fullURL} .

This will clone the repo in the project folder defined by the cwd property in the second parameter of the execSync command:

{ stdio: "inherit", cwd: destination }

NOTE
The exec and execSync methods of NodeJS use a shell to execute our command. Since we are also adding some user-provided data we need to be careful not to allow arbitrary commands to be executed (i.e. rm -rf). This is the reason for our previous validation inside index.js.

If the user sends an invalid selection (i.e. not a valid starter kit, some arbitrary commands, etc...), our code will not allow that string to be passed to execSync and be executed. We will stop everything and be safe.

As before we update the package.json file so the name of the project will be the same one the user provided.

Conclusion

I decided to make this tutorial for a reason: to show how we can make things following the example set by others (Vite in this specific case) and how we can add some of our needs on top of that.

This tutorial doesn't want to be a comprehensive explanation of how to create this kind of package. As I said before is more like a finger pointing in a direction. If you want, follow that direction, make your own mistakes along the way, and learn.

At the end of that path, you will find knowledge and maybe you'll have your own personal scaffolder!

If this article was helpful or want to start a conversation, feel free to reach out in the comments or on LinkedIn

I'll be happy to receive any feedback or ideas for future articles and tutorials.

Resources

API key management on Netlify

Donato Riccio — Sat, 08 Jul 2023 13:20:44 +0000

This is a tutorial aimed to help junior devs correctly manage their API keys (or other secrets) when publishing a website on the Netlify platform.

Pre-requisites

Basic knowledge of HTML, CSS, JavaScript
Basic knowledge of Vite, VueJS, and Axios
Basic knowledge of VisualStudio Code
Just a bit of experience with the CLI
A GitHub repository
How to deploy a website on Netlify
A website/project/web app already deployed on Netlify

What you will learn (table of contents)

How to install and use the Netlify CLI
How to set and use environment variables
How to write serverless functions
How to use serverless functions to communicate with the APIs
Conclusion
Resources

How to install and use the Netlify CLI

This is one of the easiest steps of the entire tutorial.
From the Netlify documentation about the CLI (you can find it here) this is all you need to install the Netlify CLI. Yay! :)

npm install netlify-cli -g

Now you can use the netlify command to manage your local website. You can also use the alias ntl to save some time :)

Login to Netlify

Now you need to authorize Netlify CLI by obtaining an access token. Just type the following command and authorize the application:

ntl login

Link your local environment to Netlify

If you have already deployed your website on Netlify, now you just have to link both environments together.
You can do this using this command:

ntl link

Run your build

With the following command, you can run your local build using the Netlify CLI to simulate the behavior of running the build on Netlify:

ntl dev

How to set and use environment variables

If you are not familiar with the concept of .env file and environment variables you can refer to this over-simplified definition just to understand the basics:

An .env file is just a plain text file containing key/value pairs of variables.

env is short for environment, because the values defined here are the variables available for all our environment.

Set environment variables

You can set these variables by just writing them down inside your .env file:

MY_KEY=value

NOTE: always remember to add your .env file to .gitignore or all the variables will be visible inside your repository!

Netlify UI makes the process to write and manage environment variables really easy. Just go to your site Control Panel > Site settings > Environment variables.
Write the key and the value, leaving the variable available for all the scopes (in this tutorial I will not cover the variable scopes).

NOTE: make sure to have the Sensitive variable policy set up on Require approval for untrusted deploys!
More on that here.

If you linked your local development environment to your Netlify site, you already have the environment variables available without the need to write the .env file!

You can verify this by executing the following command:

ntl env:list

Use environment variables

To use the environment variables this is all you need:

const { SECRET_API_KEY } = process.env

process.env gets all the environment variables and with a simple destructuring you can get the keys you want.

That's all for the environment variables!
Don't worry! In the next steps, I'll show you where to place this line of code :)

How to write serverless functions

A serverless function on Netlify is just a JS function that returns a promise. As per the Netlify documentation:
To create a synchronous function, use the following general syntax in your JavaScript function file to export a handler method

exports.handler = async function (event, context) {
  // your server-side functionality
};

You can also use the ES Module syntax:

const handler = async function (event, context) {
  // your server-side functionality
};

export { handler };

NOTE
Netlify provides the event and context parameters when the function is invoked.
More on that here

Where to place serverless functions

The default path used by Netlify for serverless functions is YOUR_BASE_DIRECTORY/netlify/functions.

NOTE
The function’s endpoint name is case-sensitive and determined by its filename or the name of its dedicated parent directory.

I.E. If you want an endpoint with the name hello you should save your function in one of the following ways:

netlify/functions/hello.js

netlify/functions/hello/hello.js

netlify/functions/hello/index.js

Because the endpoint name is case-sensitive if you name your function myFunction, your endpoint will look like this: netlify/functions/myFunction.js.
For the same reason if you name your function my-function, your endpoint will be: netlify/functions/my-function.js.

What to write inside the function

The easiest thing to do is to just make the function return a "Hello World!"
Using the basic example from the Netlify documentation the hello.js function will look like this:

const handler = async function (event, context) {
    // your server-side functionality
    return {
        statusCode: 200,
        body: JSON.stringify({ message: "Hello World" }),
    };
};

export { handler };

This will return an object with a statusCode and a body properties. The statusCode with value 200 means the request was successful.
The body will contain a JSON formatted string representing the object we want to get from the function. In this example is just an object with a message property.

Let's proceed to the next step!

How to use serverless functions to communicate with the APIs

Time to use your function!
After a successful test call, you will add the code needed to call the API endpoint you want.

Call the function

The following code examples are taken from a VueJS project, using axios to call both the serverless functions and the APIs.

To call hello.js from App.vue the code is as simple as this:

axios.get('/.netlify/functions/hello')
    .then((response) => {
        // handle success
        console.log(response);
        this.helloResult = response.data.message;
    })
    .catch((error) => {
        // handle error
        console.log(error);
    });

If you are a bit familiar with VueJS you'll know this code can be placed inside a function defined in the methods property or inside the mounted method.
helloResult is just a property of data and is used to memorize the value returned from the hello.js function.

NOTE
To get the "Hello World!" text you need to access the message property inside response.data.
The message property is the same property you defined in the previous step

Make sure to test your code in the browser (remember to run ntl dev or netlify dev in the terminal to get both the Netlify local environment and your project up and running as you did in the Run your build step)

If everything works on your local machine, is time to push to your repository and test again everything on your live website!

Read environment variables from the serverless function

You just tested the simplest function you could write and everything went smoothly! To make a secure call to the API you want you'll first need to read the API key from your environment variables.

Do you remember this step? This is where you find out where to place that line of code!

Go to the Set environment variables step and create a new variable called SECRET_API_KEY (spoiler: it will not be secret!) with the value you want.

On your local machine run the command to get the list of all environment variables:

ntl env:list

If you can see the SECRET_API_KEY entry, you did everything right!

NOTE
You can also check the variables values by typing y when the terminal ask you: Show values?(y/N)

Now is the time to create a new function called almost-secret.js that'll give you the value of the SECRET_API_KEY env variable.

almost-secret.js code:

const handler = async function (event, context) {
    // your server-side functionality
    const { SECRET_API_KEY } = process.env
    return {
        statusCode: 200,
        body: JSON.stringify({ message: SECRET_API_KEY }),
    };
};

export { handler };

Calling this function will give you the value of your SECRET_API_KEY variable... but, wait... why should you bring on your front-end such information?

You shouldn't! This is just an example to show how to read and use your env variables from a serverless function.
In the next example, you will see how to properly use a serverless function to call an API without exposing your API key.

Before that, let's push everything on the repository and check it on the live site.

Call QuizAPI passing the API key securely

In this last example, you will learn how to put it all together and make secure calls to every API you need.
The API used is from QuizAPI. In their documentation, they suggest attaching the API key to a request as an HTTP header:

X-Api-Key: YOUR_API_KEY

Register to QuizAPI and get your API key, then add that key to a new env variable on Netlify (es. QUIZ_API_TOKEN).
The last thing to do is to create a new function called quizapi.js. This function will call the questions endpoint (more on that here).

To make an HTTP call from a serverless function you need to import axios (you already installed the dependency in the previous steps).

NOTE
I will not cover how to use axios and how to add headers to a request since it's a pre-requisite for following this tutorial

Let's take a look at the quizapi.js function:

import axios from 'axios';

const handler = async function (event, context) {
    try {

        // your server-side functionality
        const { QUIZ_API_TOKEN } = process.env;

        const config = {
            params: {
                limit: 1
            },
            headers: {
                "X-Api-Key": QUIZ_API_TOKEN
            }
        };

        const response = await axios.get('https://quizapi.io/api/v1/questions', config)

        if (response.errors !== undefined && response.errors.length) {
            throw new Error(response.errors);
        }

        // handle success
        return {
            statusCode: 200,
            body: JSON.stringify({ response: response.data }),
        };

    } catch (error) {
        return {
            statusCode: 500,
            // Could be a custom message or object i.e. JSON.stringify(err)
            body: JSON.stringify({ response: error.message }),
        }
    }
};

export { handler };

It's a little more complex than the other two, is it?
Don't worry, I will explain this function almost line by line.

The first line just imports axios inside the function:

import axios from 'axios';

After the common code for all the Netlify serverless functions, you can spot the line taking care of retrieving the QUIZ_API_TOKEN env variable value:

const { QUIZ_API_TOKEN } = process.env;

After that, there is the code used to add parameters and header to the axios request:

const config = {
    params: {
        limit: 1
    },
    headers: {
        "X-Api-Key": QUIZ_API_TOKEN
    }
};

The limit property is a parameter taken from the QuizAPI documentation
The X-Api-Key property is where to place the value of QUIZ_API_TOKEN as explained by the QuizAPI documentation

The function will now make the call to the API, passing along parameters and headers:

const response = await axios.get('https://quizapi.io/api/v1/questions', config)

If the API responds with an error, the function will throw an exception (this is why everything is wrapped inside a try/catch block):

if (response.errors !== undefined && response.errors.length) {
    throw new Error(response.errors);
}

If there are no errors, the function will return an object already familiar to you:

return {
    statusCode: 200,
    body: JSON.stringify({ response: response.data }),
};

In the response property, we add the value of response.data since the endpoint returns an array of strings that axios put right inside the data property (if you are familiar with axios you already know how to check this).

In case of errors the function will go to the catch block and return an object with a statusCode of 500 (generic server error) and the error message:

catch (error) {
    return {
        statusCode: 500,
        // Could be a custom message or object i.e. JSON.stringify(err)
        body: JSON.stringify({ response: error.message }),
    }
}

To call this function from App.vue (or any other component) the code is almost the same as the one used before:

axios.get('/.netlify/functions/quizapi')
    .then((response) => {
        // handle success
        console.log(response);
        this.quizApiQuestion = response.data.response[0].question;
    })
    .catch((error) => {
        // handle error
        console.log(error);
    });

Test the call on your local machine

If you didn't stop the local environment, go to your browser and check if you can get a question from the QuizAPI endpoint!
After that go further and push everything on your repo to also test the call from the live site.

Test the call on the live site

If you can get a question from QuizAPI from your live website, great!

If not, maybe you are facing this kind of error: 'Error: Cannot find module '/var/task/node_modules/axios/dist/node/axios.cjs'.

To solve this error create a file called netlify.toml and add this code inside it:

[functions]
  node_bundler = "esbuild"

Commit, push, and test again!

Conclusion

When calling external API services from your front-end project always remember to keep hidden and secured your API keys (or other sensitive pieces of information).
One way to do this is to leverage the power of Netlify serverless functions that can act as API endpoints, read environment variables, and make calls to other APIs.

If this article was helpful or want to start a conversation, feel free to reach out in the comments or on LinkedIn
I'll be happy to receive any feedback or ideas for future articles and tutorials.

Resources

Laravel’s ForwardsCalls trait

Donato Riccio — Wed, 21 Jun 2023 14:01:23 +0000

In the previous article, Giuliano showed us how to leverage PHP’s Magic Methods and Late Biding to create a powerful architecture.

This, however, is neither a secret nor a new cutting-edge OOP pattern.

This same system has been used in Laravel since version 4.0* albeit in the more PHP plain way, using call_user_func_array (Laravel Model Class).

The ForwardsCalls trait has been present since version 5.7 and if you read the first part of this series you are already familiar with the concept of using this method to simplify your development. Pretty cool, right?

The devs working on the Laravel Framework thought the exact same thing (I suppose), and created the ForwardsCalls trait.

NOTE
In this article we will reference Laravel 9.x, but the principles should be valid for all the versions that implement the ForwardsCalls trait.

Everyone's using it!
The Model Class
The ForwardsCalls trait
- Digging deeper
- Pre-requisite: ExportData - part one
- The Exporter Logic
- ExportManager
- IExporter, CsvExporter, XmlExporter
- ExportData - part two
- Run the command
In conclusion

Everyone's using it!

One of the first instances where every developer using Laravel takes advantage of this approach is when they query their database through a Model.

Look at this line of code extracted from a class called ProjectController:

$projects = Project::orderByDesc('id')->get();

Pretty ordinary, right?

If you would dive deeper in the orderByDesc method, where would you go looking?
Probably inside the Project class.

Now, if you have some experience with Laravel, you already know this Project class is almost empty because it inherits all of its properties and methods from the Model abstract class.

Inside the Model class we go!

The Model Class

Once here we can see that this abstract class implements a lot of interfaces and uses a good number of traits, but we are looking for a specific method: orderByDesc.

So we open the find window, type our string and find… nothing.

The method is not defined in this class. We can search inside every trait but without results. Seems like the orderByDesc method is non-existent.

Every good developer should now think: how is this possible?

The answer lies in the ForwardsCalls trait, PHP Magic Methods (__call and __callStatic), and in the Late Binding!
In the first part of this series, Giuliano did a great job explaining how to re-create this pattern with a couple of classes in plain PHP, so I will not repeat what he already said.

Long story short: the Model class makes use of the ForwardsCalls trait (you can see that just by opening the class).
If you start to explore this class you will find both the __call and __callStatic methods and see the __callStatic method do a Late Binding to invoke the requested method as non-static:

return (new static)->$method(...$parameters);

This way every static method not defined inside the Model class will be redirected to a non-static method (still not defined in this class) and will trigger the __call magic method.

Inside the __call magic method we can see a couple of if-blocks, but what we are looking for is the last line:

return $this->forwardCallTo($this->newQuery(), $method, $parameters);

What’s going on here?

The ForwardsCalls trait

The previous code is calling the forwardCallTo method, defined inside the ForwardsCalls trait (what a surprise!), passing along 3 parameters:

the first is a Query Builder instance (where the orderByDesc method is defined!)
the second is the name of the method we invoked (again, orderByDesc)
the third is the parameters we used ('id' in the previous example)

Now is the right moment to ask: why didn’t the developers keep using the more straightforward call_user_func_array method?

There are a good number of reasons understandable by looking at the ForwardsCalls trait:

the framework has better exception management (look at how the exceptions are handled inside this trait)
the framework has more flexibility (look at both forwardCallTo and forwardDecoratedCallTo methods)
the developers avoid code repetition inside every class (they just need to use the trait and write a couple of lines for the magic methods)
and more...

This is a great example of a developer-friendly pattern 🙂

Digging deeper

How could we take advantage of this pattern?
It's time to put our hands on some code!

Just imagine this scenario: you are developing an e-commerce and now you have the need to export your data in various formats (i.e. XML and CSV).
Because you don't need a UI to get these exports, you will create an Artisan Command to run your code right from the terminal.

Pre-requisite: ExportData - part one

Don't be scared if you are not familiar with the creation of Artisan Commands: the code is super simple and you don't need to understand it to follow this tutorial.
To keep things even more simple our export classes will not really export data.

NOTE
If you want to learn about Artisan Commands check out the corresponding section inside the Laravel documentation

To create a new command we just need to run:

php artisan make:command ExportData

This command will create the ExportData class inside app\Console\Commands.
Looking at the code we can clearly see two properties and the handle method. Maybe another time I will better explain how Artisan Commands works, but it's not the point of this article.

Quoting directly from the documentation:

After generating your command, you should define appropriate values for the signature and description properties of the class. These properties will be used when displaying your command on the list screen. The signature property also allows you to define your command's input expectations. The handle method will be called when your command is executed. You may place your command logic in this method.

So let's copy this code for the $signature property:

protected $signature = 'data:export
                        {type : The export format: XML, CSV}
                        {class : The class to export: Product, User}';

And this is for the $description property:

protected $description = 'Export selected data in the given format';

In the handle method we will echo the sentence "it works" and test everything running the command:

php artisan data:export xml product

If you see it works in the terminal, great! You just successfully ran your custom command!
Now it's time to create the export logic and make use of the ForwardsCalls trait.

The Exporter Logic

Our exporter will be structured this way:

The main ExportManager class, taking care of the general logic
The IExporter interface, defining how the single exporter is implemented
A couple of classes for the exporter logic: CsvExporter and XmlExporter implementing IExporter

All these classes are placed inside app\Support (the full project is available on GitHub).
How do they work?

ExportManager

The ExportManager use the ForwardsCalls to redirect most of the calls to the dedicated exporter class.
Inside this class, you can see both __call and __callStatic magic methods, a couple of static methods (list and sendExport), and the private method getExporter.
If you read the first part of this article's series you are already familiar with how these magic methods work.

The __call method gets the type and model from the $parameters array and capitalizes them (i.e. xml -> Xml, PRODUCT -> Product).
After that it calls the forwardCallTo method, passing an instance of the selected Exporter, the $method called by our code, and the $parameters array (just in case we should need it).

To get the correct Exporter instance (i.e. CsvExporter, XmlExporter, etc...) the ExportManager use the getExporter method.
This method returns an instance created dynamically from both $type and $model parameters.

/**
 * Create an exporter instance
 * 
 * @param string $type the Exporter type (i.e. Csv)
 * @param string $model the model to use in the export (i.e. Product)
 * 
 * @return mixed an instance of the exporter (i.e. CsvExporter, XmlExporter, etc...)
 */
private function getExporter($type, $model)
{
    try {

        // $type = Csv -> App\Support\Exporters\CsvExoporter
        $exporter = "App\\Support\\Exporters\\{$type}Exporter";

        // $model = Product -> App\Models\Product
        $data = "App\\Models\\{$model}";

        // new App\Support\Exporters\CsvExoporter(App\Models\Product)
        return new $exporter($data);
    } catch (Error | Exception $e) {
        throw $e;
    }
}

This way we get the instance of the export, initialized with the model it will use to get the data from the database.
The ExportManager class act both as a manager for the exports (it can list them or send a particular report to the administrator) and as a switch to call the class needed for the selected type of export (using the Dynamic Class Instantiation).

IExporter, CsvExporter, XmlExporter

The IExporter interface allows us to create code that specifies which methods the exporters must implement, without having to define how these methods are implemented:

interface IExporter
{
    /**
     * Get the data from the model and prepare the export
     */
    public function prepareExport();

    /**
     * Create the export
     */
    public function export();

    /**
     * Save the export inside the database
     */
    public function save();
}

Using an interface we define the basic standard for all the exporters we will create, allowing us to create objects of different classes that may be used interchangeably because they implement the same interface.
This is what we want for all our current and future exporters.

Now let's take a look at one of the exporters (for the sake of simplicity both the exporters do almost the same things, but of course, they can do different operations).

class CsvExporter implements IExporter
{
    public static $filetype = "CSV";
    private $items;
    private $model;
    public $lastExportId;

    public function __construct($_model)
    {
        $this->model = $_model;
    }

    public function prepareExport()
    {
        $this->items = $this->model::all();

        echo "Preparing export of " . get_class(new $this->model);
        echo "\n";
    }

    public function export()
    {
        $this->prepareExport();

        echo "{$this->items->count()} records exported in " . static::$filetype . " format";
        echo "\n";

        return $this;
    }

    public function save()
    {
        $this->lastExportId = rand(1, 1305);

        echo "Export n. {$this->lastExportId} saved inside database";
        echo "\n";

        return $this;
    }
}

Feel free to download the example project and add your custom exporter! Get your hands dirty it's a great way to wrap your head around this kind of pattern.

Remember to create a DB and run all the migrations and seeder before running the data:export command.

Basically, every exporter is instantiated with a model, use this model to get all the records and simulate a DB writing.
The export and save methods return an instance of the export class so that we can chain the methods calls and also get the instance in our DataExport class.

NOTE
We get the exporter instance (CsvExporter, XmlExporter, etc...) because we are using the forwardCallTo method inside __call in our ExportManager class.

If we had used the forwardDecoratedCallTo method, we would have got an instance of ExportManager. Try it!

With all this logic out of the way we have only one more thing to do: add the correct code in the DataExport handle method.

ExportData - part two

Remember our handle method that does nothing more than echo "it works"? It's time to make it work for real!
We need to import the ExportManager class by writing use App\Support\ExportManager; before the class definition.

In the handle method we can now call the export method on the ExportManager (even if it's defined on the specific exporter) and get the correct instance.
With this instance we can then call sendReport, pass it the ID of the export we just created, and have it sent to the administrator inbox.

public function handle()
{
    $export = ExportManager::export($this->argument('type'), $this->argument('class'))->save();
    ExportManager::sendExport($export->lastExportId);
}

Run the command

Finally, you can test if everything it's working by running this command:

php artisan export:data csv product

Our data is exported in the format we want! Yay!
The logic we implemented allowed us to create a very flexible exporter: we can export all the Models defined in our Laravel application and should we need a different kind of exporter (i.e. PdfExporter, ExcelExporter, etc...) we just need to create a new class caring only about the exporting logic and nothing more!

In conclusion

It was a wild ride, wasn't it?
I hope this helped you better understand one of the gems hidden inside the Laravel Framework!

The ForwardsCalls trait gives us a powerful pattern to leverage when developing inside a Laravel application. It gives us a lot of flexibility and the possibility to keep our classes clean, well defined but still able to communicate.

Giuliano also showed us how to bring this pattern outside Laravel and use it virtually in every PHP project we want.

I enjoyed writing this article's series with Giuliano and I really hope this article inspired you to dig a little bit inside the code of the libraries and frameworks you use.

Here you can find the first half made by Giuliano. ;)

If this article was helpful or want to start a conversation, feel free to reach out in the comments or here @gosty93 and @donato-riccio-wda
We'll be happy to receive any feedback or ideas for future articles and tutorials.
Happy Coding | _ 0

This is the earliest version you could find on their public repository

DEV Community: Donato Riccio

Create your custom npm template package

a.k.a what npm create vite@latest does

Table of Contents

What we want

Before you continue

Try the package

The easiest way (template repository)

The npm create way

The npm create command

Package requirements

main / exports

bin

A really basic package

A simple console.log

Make the package available globally on your local machine

How to manage a more complex scaffolding

A simple scaffolding package

Create a new project

A crossroad

One package, many files

Update the scaffolding of the npm package

How to interact with the user and copy the scaffolding files

One package, many repos

A new old repo

How to interact with the user and install the starter kit

Conclusion

Resources

API key management on Netlify

Pre-requisites

What you will learn (table of contents)

How to install and use the Netlify CLI

Login to Netlify

Link your local environment to Netlify

Run your build

How to set and use environment variables

Set environment variables

Use environment variables

How to write serverless functions

Where to place serverless functions

What to write inside the function

How to use serverless functions to communicate with the APIs

Call the function

Read environment variables from the serverless function

Call QuizAPI passing the API key securely

Test the call on your local machine

Test the call on the live site

Conclusion

Resources

Laravel’s ForwardsCalls trait

Table of contents

Everyone's using it!

The Model Class

The ForwardsCalls trait

Digging deeper

Pre-requisite: ExportData - part one

The Exporter Logic

ExportManager

IExporter, CsvExporter, XmlExporter

ExportData - part two

Run the command

In conclusion

a.k.a what `npm create vite@latest` does

The `npm create` way

A simple `console.log`