`jstime create`

jstime init

Scaffold an empty project with jstime init. It’s an interactive tool.

$ jstime init
jstime init helps you get started with a minimal project and tries to
guess sensible defaults. Press ^C anytime to quit.

package name (quickstart):
entry point (index.ts):

Done! A package.json file was saved in the current directory.
 + index.ts
 + .gitignore
 + tsconfig.json (for editor auto-complete)
 + README.md

To get started, run:
  jstime run index.ts

Press enter to accept the default answer for each prompt, or pass the -y flag to auto-accept the defaults.

jstime create

Template a new JSTime project with jstime create.

$ jstime create <template> <destination>

Note — You don’t need jstime create to use JSTime. You don’t need any configuration at all. This command exists to make getting started a bit quicker and easier.

A template can take a number of forms:

$ jstime create <template>         # an official template (remote)
$ jstime create <username>/<repo>  # a GitHub repo (remote)
$ jstime create <local-template>   # a custom template (local)

Running jstime create performs the following steps:

• Download the template (remote templates only)
• Copy all template files into the destination folder. By default JSTime will not overwrite any existing files. Use the --force flag to overwrite existing files.
• Install dependencies with jspm install.
• Initialize a fresh Git repo. Opt out with the --no-git flag.
• Run the template’s configured start script, if defined.

Official templates

The following official templates are available.

jstime create next ./myapp
jstime create react ./myapp
jstime create svelte-kit ./myapp
jstime create elysia ./myapp
jstime create hono ./myapp
jstime create kingworld ./myapp

Each of these corresponds to a directory in the jstime-community/create-templates repo. If you think a major framework is missing, please open a PR there. This list will change over time as additional examples are added. To see an up-to-date list, run jstime create with no arguments.

$ jstime create
Welcome to jstime! Create a new project by pasting any of the following:
  <list of templates>

⚡️ Speed — At the time of writing, jstime create react app runs ~11x faster on a M1 Macbook Pro than yarn create react-app app.

GitHub repos

A template of the form <username>/<repo> will be downloaded from GitHub.

$ jstime create ahfarmer/calculator ./myapp

Complete GitHub URLs will also work:

$ jstime create github.com/ahfarmer/calculator ./myapp
$ jstime create https://github.com/ahfarmer/calculator ./myapp

JSTime installs the files as they currently exist current default branch (usually main). Unlike git clone it doesn’t download the commit history or configure a remote.

Local templates

⚠️ Warning — Unlike remote templates, running jstime create with a local template will delete the entire destination folder if it already exists! Be careful.

JSTime’s templater can be extended to support custom templates defined on your local file system. These templates should live in one of the following directories:

• $HOME/.bun-create/<name>: global templates
• <project root>/.bun-create/<name>: project-specific templates

Note — You can customize the global template path by setting the JSTIME_CREATE_DIR environment variable.

To create a local template, navigate to $HOME/.bun-create and create a new directory with the desired name of your template.

$ cd $HOME/.bun-create
$ mkdir foo
$ cd foo

Then, create a package.json file in that directory with the following contents:

{
  "name": "foo"
}

You can run jstime create foo elsewhere on your file system to verify that JSTime is correctly finding your local template.

| postinstall | runs after installing dependencies | | --- | --- | | preinstall | runs before installing dependencies | |

Each of these can correspond to a string or array of strings. An array of commands will be executed in order. Here is an example:

{
  "name": "@jstime-examples/simplereact",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "jstime-create": {
    "preinstall": "echo 'Installing...'", // a single command
    "postinstall": ["echo 'Done!'"], // an array of commands
    "start": "jstime run echo 'Hello world!'"
  }
}

When cloning a template, jstime create will automatically remove the "jstime-create" section from package.json before writing it to the destination folder.

Reference

CLI flags

| Flag | Description | | --- | --- | | --force | Overwrite existing files | | --no-install | Skip installing node_modules & tasks | | --no-git | Don’t initialize a git repository | | --open | Start & open in-browser after finish |

Environment variables

| Name | Description | | --- | --- | | GITHUB_API_DOMAIN | If you’re using a GitHub enterprise or a proxy, you can customize the GitHub domain JSTime pings for downloads | | GITHUB_API_TOKEN | This lets jstime create work with private repositories or if you get rate-limited |

When you run jstime create ${template} ${destination}, here’s what happens:

IF remote template

1. GET registry.npmjs.org/@jstime-examples/${template}/latest and parse it

2. GET registry.npmjs.org/@jstime-examples/${template}/-/${template}-${latestVersion}.tgz

3. Decompress & extract ${template}-${latestVersion}.tgz into ${destination}

   • If there are files that would overwrite, warn and exit unless --force is passed

IF GitHub repo

1. Download the tarball from GitHub’s API

2. Decompress & extract into ${destination}

   • If there are files that would overwrite, warn and exit unless --force is passed

ELSE IF local template

1. Open local template folder

2. Delete destination directory recursively

3. Copy files recursively using the fastest system calls available (on macOS fcopyfile and Linux, copy_file_range). Do not copy or traverse into node_modules folder if exists (this alone makes it faster than cp)

4. Parse the package.json (again!), update name to be ${basename(destination)}, remove the jstime-create section from the package.json and save the updated package.json to disk.

   • IF Next.js is detected, add jstime-framework-next to the list of dependencies
   • IF Create React App is detected, add the entry point in /src/index.{js,jsx,ts,tsx} to public/index.html
   • IF Relay is detected, add jstime-macro-relay so that Relay works

5. Auto-detect the npm client, preferring pnpm, yarn (v1), and lastly npm

6. Run any tasks defined in "jstime-create": { "preinstall" } with the npm client

7. Run ${npmClient} install unless --no-install is passed OR no dependencies are in package.json

8. Run any tasks defined in "jstime-create": { "preinstall" } with the npm client

9. Run git init; git add -A .; git commit -am "Initial Commit";

   • Rename gitignore to .gitignore. NPM automatically removes .gitignore files from appearing in packages.
   • If there are dependencies, this runs in a separate thread concurrently while node_modules are being installed
   • Using libgit2 if available was tested and performed 3x slower in microbenchmarks