How to use the command 'surge' (with examples)

The ‘surge’ command is a tool for simple web publishing. It allows users to easily publish their websites to the web using the surge.sh service. Surge.sh provides a fast, easy, and free way to host static sites. It is especially useful for quickly deploying static websites for testing or demonstration purposes.

Use case 1: Upload a new site to surge.sh

Code:

surge path/to/my_project

Motivation: The motivation for using this example is to quickly upload a new website to surge.sh for testing or demonstration purposes. Suppose you have just finished developing a static website project named ‘my_project’ locally and you want to publish it to the web to showcase your work. By using the ‘surge’ command with the path to your project, surge.sh will create a unique subdomain for your site and make it accessible on the web.

Explanation: The command ‘surge’ followed by the path to the project directory tells the surge.sh service to upload the contents of that directory to the web. Surge.sh takes care of generating a unique subdomain for your project and handles the hosting for you.

Example output:

    surge.sh - Surge - surge.sh

        email: john@example.com
        token: *********************

            project: /path/to/my_project
               size: 2 files, 1.3 MB
             domain: my_project.surge.sh
             upload: [====================] 100% eta: 0.0s

            propagate on DNS:
             - my_project.surge.sh

In the example output, surge.sh displays information about the upload process, including the project size, generated domain name, and progress bar.

Use case 2: Deploy site to custom domain

Code:

surge path/to/my_project my_custom_domain.com

Motivation: The motivation for using this example is to deploy your website to a custom domain instead of using the surge.sh subdomain. If you have already registered a domain name and want to associate your surge.sh site with it, you can use the ‘surge’ command with the path to your project directory and your custom domain name.

Explanation: The command ‘surge’ followed by the path to the project directory and the desired custom domain tells surge.sh to deploy your website to the specified custom domain. However, it is important to note that you must have appropriate DNS records that point your custom domain to the surge.sh subdomain.

Example output:

    surge.sh - Surge - surge.sh

        email: john@example.com
        token: *********************

            project: /path/to/my_project
               size: 2 files, 1.3 MB
             domain: my_custom_domain.com
             upload: [====================] 100% eta: 0.0s

            propagate on DNS:
             - my_custom_domain.com

In the example output, surge.sh displays the same information as before, but with the custom domain name instead of the surge.sh subdomain.

Use case 3: List your surge projects

Code:

surge list

Motivation: The motivation for using this example is to quickly obtain a list of all your surge projects. This can be useful when you have multiple projects hosted with surge.sh and want to check their details or manage them.

Explanation: The command ‘surge list’ tells the surge.sh tool to retrieve and display a list of all the surge projects associated with your account. It provides information such as project URL, size, and deployment status.

Example output:

    surge.sh - Surge - surge.sh

        email: john@example.com
        token: *********************

            Projects:
            - /path/to/my_project (my_project.surge.sh)
            - /path/to/another_project (another_project.surge.sh)

In the example output, surge.sh lists two projects associated with the account, along with their URLs.

Use case 4: Remove a project

Code:

surge teardown my_custom_domain.com

Motivation: The motivation for using this example is to remove a project from surge.sh. You may want to remove a project if you no longer need to host it or if you want to free up a custom domain for use with another project.

Explanation: The command ‘surge teardown’ followed by the custom domain name tells surge.sh to remove the project associated with that custom domain from surge.sh. This will result in the site being taken down and the custom domain becoming available for use with other surge projects.

Example output:

    surge.sh - Surge - surge.sh

        email: john@example.com
        token: *********************

            project: my_custom_domain.com
               size: 12 files, 4.7 MB
             status: NOT BOOLEAN, -3

In the example output, surge.sh confirms the removal of the project and displays its size and status.