Gratuitous Animation

I made this with SVG and the JavaScript animation API. You can do this yourself, but not until you set up your tools. This document will show you how to install modern JavaScript programming tools. You're just a few minutes away from writing and running your own code.

Script Test

Hello world, my name is «See assignment #1 for details.»!

Purpose & Background

The JavaScript ecosystem has become so complicated. Even if you know the basic language, it is hard to use unless you understand the common tools and libraries.

This document will get you set up with a minimum reasonable set of tools. And it will set you up with a template for a minimum project. This is a perfect starting place for a new projects. And if you need to install more tools and libraries, you'll be all ready for that.

There are viable alternatives to most of these tools. However, I recommend you start here before you explore on your own.

My Tools

Install these once per computer.

VS Code

There are a lot of useful extensions and such that work with VS Code. It's the only editor I use for web stuff.

Install & Configure

• Download from here.
• Install the following extensions:
  • Code Spell Checker
  • JavaScript and TypeScript Nightly
  • Vite (The Anthony Fu version.)
  • Prettier (Any time VS Code asks me which formatter to use, I pick the one with “prettier” in the name.)
• Main menu ⇒ Code ⇒ Preferences ⇒ Settings. Search for git autofetch and set it to true.

git

You do not need to be an expert in git, but you will need the git command line tools to follow these and other directions.

Install

On my Mac I started from the terminal and typed git. I clicked OK a few times and eventually an installer came up and did its job.

Configure

Type the next couple of lines at the terminal. Use your own name and email. These will be recorded as part of every commit.

The following is not strictly required, but I like to type git plog. “P” is for “Philip”.

npm & Node

npm is the hub for JavaScript libraries and tools. Initially I tried to avoid it because it was so big and complicated, but npm is essential. Some tools and libraries are available multiple ways, but I always recommend using npm if you get the choice.

npm stands for Node Package Manager. The program you're about to write is a package. Each library you want to use is a package. A lot of your development tools are packages. npm is a repository for packages and a tool for downloading, installing, building, testing and otherwise manipulating packages.

npm works well with git and a lot of other relevant tools. I use npm as part of my normal build and test processes.

Install

This process changes frequently. Currently the internet says to follow the directions on Node's homepage.

In the past I've used NVM and other tools to install npm and Node. The process used to be complicated and bug-ridden. It looks like the standard installer works better now.

TypeScript

If you don't know TypeScript, learn it. It gives you all of the nice safety features of C++/Java/C#, but without breaking any of the nice parts of JavaScript. I never use plain JavaScript if I can help it.

Install

Open a terminal window. Make sure you are not inside an npm project. (Otherwise you will eventually get the “This is not the tsc command you are looking for” error with the oversized red background.) Type npm install -g typescript.

GitHub

You don't need a GitHub account to use these tools. But if you have a GitHub account and you are installing dev tools on a new computer you probably want to do this. This lets tools on your computer access your GitHub account without asking for your password each time.

At the terminal type ssh-keygen and take all the defaults. This will create a new pair of cryptographic keys.

Type cat ~/.ssh/id_rsa.pub to display your new public key.

Go to https://github.com/settings/keys and add your new public key.

Vite

I always use Vite to manage my projects. Vite takes care of a lot of annoying details related to using 3rd party libraries and to testing and releasing your code.

Install

You do not need to install this on your computer. You will automatically get these tools when you start a new project through any of the methods described below. npm takes care of installing and upgrading this tool.

Use

cd into your project directory. That's the default if you are using the terminal build into VS Code.

Type npm run dev to start a test server. (Sometimes VS Code will do this for you automatically.) This will display instructions and status on the standard output. Any time you modify a file, the dev server will automatically rebuild (if required) and push the changes to the browser.

By default the development web server only handles local requests. But that's easy to change so you can test on your phone's browser.

Type npm run build to pack your code up for a normal web server. My template, below, is configured to work with GitHub's free hosting.

degit

degit is a tool for creating a new project from a template. Typically the template and the new project are both stored in GitHub repositories.

Install

Type npm install -g degit at the command line.

Try It!

Here are several ways to create a project.

git clone

Use this method to start from an existing project. For example type git clone https://github.com/TradeIdeasPhilip/typescript-getting-started to copy the source for this document to your computer. This will create a directory called typescript-getting-started in the current directory on your local machine. Start VS Code and open that directory to start work.

Assignment #1

Clone this project.

Start this project up in development mode. (Remind me how.)

At the top, where it says “my name is,” fill in your own name. Do it using TypeScript, not HTML. Keep the highlight formatting.

And remove all that round Earth propaganda from the title. Replace it with something more appropriate like 𝔱𝔰 or 𝕋𝕤 or 𝒯𝒮 or 𝑇𝑆.

View your changes in development mode.

Need help? Check out this video.

degit template

Type degit https://github.com/TradeIdeasPhilip/typescript-template new-project-name. This will create a new directory called new-project-name in the current directory with the contents of the template. Open this directory in VS Code and start creating.

Some people use the word “scaffolding,” rather than “template.”

Assignment #2

Start a new project from this template. Add a small amount of custom HTML, CSS, and TypeScript. Build the project and publish it to GitHub pages.

See my solution and more in this video.

npm create vite@latest

You can create a new project using Vite by typing npm create vite@latest. This will use a template provided by Vite. This will include instructions and examples to help you learn Vite.

Assignment #3

Explore Vite.

About This Document

Source Code

See my GitHub repository for the source code for this document. This document was created using the tools I've described here, and serves as an example of my process.

Source Materials

I started from https://github.com/TradeIdeasPhilip/bounce-3d?tab=readme-ov-file#starting-from-scratch.

I added degit. I removed the git sub module stuff. And I updated some other sections.

Fonts

Peralta is readable and fun, perfect for headers.

New Tegomin reminds me of Snoopy. “It was a dark and stormy night...” Mostly I love it, but I'm not crazy about the "normal" quotes or the “smart” [sic] quotes.

Redacted Script always brings a smile to my face.