Deploy your Vue.js Application with the Twilio Serverless Toolkit

November 12, 2021
Written by

Deploy your Vue.js Application with the Twilio Serverless Toolkit

When you are ready to deploy your Vue.js application you are faced with the problem of selecting a hosting platform. For this there are lots of options, but many require you to set up and manage your own server or container.

In this short tutorial I want to introduce you to the Twilio Runtime, a serverless hosting platform that when paired with the Twilio Serverless Toolkit makes deploying your front end application as easy as typing yarn deploy on your terminal.

Requirements

To work on this tutorial you will need the following items:

Prepare your Vue.js application

To follow this tutorial you’ll need a Vue application to deploy to the cloud. The easiest way to have a sample application is to create a brand new one using the Vue CLI. In your terminal, navigate to a suitable parent directory and then run the following commands:

vue create vue-twilio-serverless
cd vue-twilio-serverless

You should now be able to run the Vue.js application locally with the following command:

yarn serve

After a few seconds a new tab in your browser will show the Vue starter application:

Vue development server demo

If you decide to use your own application instead of a brand new one, make sure that you can build your application using yarn build (or alternatively npm run build), as you are going to use this command as part of the serverless deployment.

Once you have verified that the application runs correctly in your local environment, you can stop it with Ctrl-C.

Add Twilio Serverless to the project

In this section you are going to add Twilio Serverless support to the Vue project.

Install the Twilio CLI

The Twilio Serverless Toolkit is distributed as a plugin to the Twilio CLI, so the next step is to install the CLI. Run the following command:

npm install -g twilio-cli

You can find detailed installation instructions for the Twilio CLI on the Twilio CLI Quickstart page.

Install the Twilio Serverless Toolkit

The Twilio Serverless Toolkit is a Twilio CLI plugin. Install it as follows:

twilio plugins:install @twilio-labs/plugin-serverless

The detailed installation instructions are in the documentation.

Connect the CLI to your Twilio account

The Twilio CLI will be issuing API calls to Twilio on your behalf, so it needs to know your credentials so that it can authenticate. You can run the following command to configure the Twilio CLI with your Twilio account:

twilio login

You will need to enter your Twilio Account SID and Auth Token. You can find these in the Twilio Console. You will also be asked to enter a profile name under which the credentials will be stored. You can use default or any name of your choice.

Create a Twilio Serverless project

In this step you are going to add the project files required by the Twilio Serverless Toolkit in a subdirectory of the Vue project. Run the following command from the top-level Vue project directory:

twilio serverless:init serverless --empty

After the command completes, you are going to have a new serverless subdirectory, with some files and subdirectories of its own.

The serverless/assets subdirectory is the default location where the static assets to be deployed are to be copied. In this tutorial, the Serverless Toolkit will be configured to use the dist directory of the Vue project as the assets folder, so the assets subdirectory is not used. You can just leave it there, or delete it if you prefer.

The serverless/functions subdirectory is not going to be used in this tutorial, but it can sometimes be very useful, as it provides a location where back end code for the project can be defined as part of the deployment. Having the option to create a serverless back end is one of the features of the Twilio Runtime that sets it apart from other serverless options such as GitHub Pages, which are limited to only deploy static assets.

Deploy the project to the cloud

To deploy the Vue application two things need to happen:

  1. The project needs to be built. In most cases this is done by running yarn build, which in turn runs the Vue CLI to build the project.
  2. The Twilio Serverless Toolkit’s deploy command must be issued, using the dist directory generated in step 1 as the source of the static assets to deploy.

To make the deployment experience as convenient as possible, you are going to define a yarn deploy command in the package.json file that runs these two actions back to back. Open package.json in your favorite text editor, and locate the scripts section, which should look more or less like this:

  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint"
  },

Right after the definition of the build command, add the deploy command as follows:

  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "deploy": "vue-cli-service build && twilio serverless:deploy --service-name vue-twilio-serverless --cwd serverless --assets-folder ../dist",
    "lint": "vue-cli-service lint"
  },

The deploy command runs two commands, separated by &&. The first command is the build command defined by Vue. This ensures that the front end project is up to date when the deployment takes place. If you use a non-standard build command, make sure to enter it here.

The serverless deployment command is in the second part. This is the twilio serverless:deploy command with a few options:

  • --service-name vue-twilio-serverless provides a name for the deployment. This name is going to be used in the URL that the Twilio Runtime will assign to the deployed project. Feel free to use a different name if you like.
  • --cwd serverless tells the toolkit that the top-level directory for the Twilio Serverless Toolkit project is in the serverless subdirectory.
  • --assets-folder ../dist configures the location of the static assets as the dist directory generated by the Vue build process. This directory is given as a relative path starting from the serverless directory.

If you don’t like to have such a long command line, the deployment options can also be given in a config file. In that case, find the file named .twilioserverlessrc in the serverless subdirectory and set your options there, and then the only option you need to keep in the command is --cwd serverless.

Are you ready to deploy? Just run the newly created command:

yarn deploy

After a few seconds, the output of the command will give you the public URLs assigned to all the assets of your Vue application. Find the index.html file in this list:

Assets:
   ...
   https://vue-twilio-serverless-1234-dev.twil.io/index.html
   ...
✨  Done in 23.33s.

You can use this URL to access your application from anywhere in the world!

Default index page

When you test your new deployment, you will notice that you have to explicitly include the index.html page in the URL. Most deployment platforms implement a default for the filename portion of the URL, so that it can be omitted when it is index.html.

The Twilio Runtime has a strange and hacky way to do this. The default page has to be uploaded with the path assets/index.html and then it will be served from the root URL by default. Adding this directory and default page can be incorporated into the deploy command. Here is the updated scripts section in package.json:

  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "deploy": "vue-cli-service build && mkdir dist/assets && cp dist/index.html dist/assets && twilio serverless:deploy --service-name vue-twilio-serverless --cwd serverless --assets-folder ../dist",
    "lint": "vue-cli-service lint"
  },

This new version of the deploy command adds mkdir dist/assets and cp dist/index.html dist/assets right before the project is deployed. And with this small change, you can now access your Vue application on the root URL of your assigned domain.

Upgrading your deployment

As you continue to work with your Vue application you will make changes, and will need to upgrade the deployed version. To refresh this deployment, just run the yarn deploy command again, and all the assets will be re-uploaded.

You may have noticed that the subdomain assigned to your deployed project has a -dev suffix. Twilio Runtime deployments can have multiple environments, with dev used as the default. Using environments you can create a sophisticated production deployment workflow where for example, a build is deployed to the dev environment for initial testing, promoted to a staging environment for more intensive testing, and finally promoted again to the prod environment for public use. The Twilio Serverless Toolkit includes a promote option to enable these advanced workflows.

To keep your local project linked to your deployment, you can add all the files in the serverless subdirectory to your project’s source control. The file that links the local project to the deployed version named .twiliodeployinfo. Note that this file is only created after your first deployment.

Using a custom domain

The Twilio serverless platform does not currently support custom domain names. The domain name under which your application is deployed is determined by Twilio, and is always a subdomain of twil.io.

The currently recommended solution to use a custom domain name for your deployment is to connect a reverse proxy server in front of the Twilio deployed application, and access the application through the proxy. If you have access to a host, then you can manually configure Nginx with your own domain and SSL certificate on it, and have it forward all requests to the URL assigned by the Twilio Runtime. If you prefer to stay in the serverless realm, then a Cloudflare worker can be programmed to act as a proxy to another site.

Client-Side routing

If your application uses client-side routing, then you have to configure your router to put the route in the fragment portion of the URL, because the Twilio Runtime will not be able to process routes that are part of the URL path correctly at this time. This is the default behavior for the Vue Router module, so in general this shouldn’t be a problem, but keep in mind that if the router is configured in history mode then shortcuts to internal routes will not work.

Conclusion

I hope you found the Twilio Runtime a viable option for the deployment of your front end projects. This is a powerful serverless platform that also gives you the option to implement a Node.js back end for your application. Consult the Twilio Runtime documentation to learn about all of its features and the front end deployment guide if you want to learn more about front end deployment options.

I can’t wait to see what you deploy with the Twilio Runtime!

Miguel Grinberg is a Principal Software Engineer for Technical Content at Twilio. Reach out to him at mgrinberg [at] twilio [dot] com if you have a cool project you’d like to share on this blog!