feat: dfx new templates (#3499)

Also closes #2771.
dfinity · Feb 9, 2024 · bd13729 · bd13729
1 parent 3d16173
commit bd13729
Show file tree

Hide file tree

Showing 145 changed files with 2,031 additions and 395 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 # UNRELEASED
 
+### feat: new starter templates
+
+`dfx new` now has a new set of customizable project templates and an interactive menu for selecting them. Supports the Svelte, Vue, and React frameworks, and Azle and Kybra backends.
+
+### fix: --no-frontend no longer creates a frontend
+
+Previously `dfx new --no-frontend` still created a frontend canister. This behavior is now accessed via `--frontend simple-assets`.
+
 ### feat: `dfx cycles redeem-faucet-coupon`
 
 It is now possible to redeem faucet coupons to cycles ledger accounts.

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/docs/cli-reference/dfx-new.md b/docs/cli-reference/dfx-new.md
@@ -4,6 +4,8 @@ Use the `dfx new` command to create a new project for the IC. This command creat
 
 You can use the `--dry-run` option to preview the directories and files to be created without adding them to the file system.
 
+If called without any arguments besides the project name, it will interactively prompt you for the values of `--type`, `--frontend`, and `--extras`.
+
 ## Basic usage
 
 ``` bash
@@ -14,11 +16,13 @@ dfx new _project_name_ [flag]
 
 You can use the following optional flags with the `dfx new` command:
 
-| Flag              | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
-|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--dry-run`       | Generates a preview the directories and files to be created for a new project without adding them to the file system.                                                                                                                                                                                                                                                                                                               |
-| `--frontend`      | Installs the template frontend code for the default project canister. The default value for the flag is `true` if `node.js` is currently installed on your local computer. If `node.js` is not currently installed, you can set this flag to `true` to attempt to install `node.js` and the template file when creating the project or you can set the flag to `false` to skip the installation of template frontend code entirely. |                                                                                                                                                                                                                                                                                    |
-| `--no-frontend`      | Skips installing the frontend template code and instead creates an asset canister with a dummy `.txt` file. This is the default behavior if `node.js` is currently not installed on your computer. |
+| Flag                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--dry-run`             | Generates a preview of the directories and files to be created for a new project without adding them to the file system.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `--extras <EXTRAS>`     | Comma-separated list of additional features to add to the project template. `bitcoin` and `internet-identity` will insert the appropriate boilerplate into `dfx.json`, and `frontend-tests` adds a `vitest` skeleton to the frontend project.                                                                                                                                                                                                                                                             |
+| `--frontend <FRONTEND>` | Installs the template frontend code for the default project canister. The default value for the flag is `vanilla` if `node.js` is currently installed on your local computer. If `node.js` is not currently installed, you can set this flag to attempt to install `node.js` and the template file when creating the project or you can set the flag to `none` to skip the installation of template frontend code entirely. Possible values: `svelte`, `react`, `vue`, `vanilla`, `plain-assets`, `none`. |
+| `--no-frontend`         | Skips installing the frontend template code. This is the default behavior if `node.js` is currently not installed on your computer. Equivalent to `--frontend none`.                                                                                                                                                                                                                                                                                                                                      |
+| `--type <TYPE>`         | Selects the template backend code for the default project canister. The default value for the flag is `motoko`. Possible values: `motoko`, `rust`, `azle`, `kybra`.                                                                                                                                                                                                                                                                                                                                       |
 
 ## Arguments
 

diff --git a/docs/dfx-json-schema.json b/docs/dfx-json-schema.json
@@ -237,6 +237,14 @@
               "enum": [
                 "assets"
               ]
+            },
+            "workspace": {
+              "title": "NPM workspace",
+              "description": "The workspace in package.json that this canister is in, if it is not in the root workspace.",
+              "type": [
+                "string",
+                "null"
+              ]
             }
           }
         },
@@ -1068,4 +1076,4 @@
       ]
     }
   }
-}
+}
diff --git a/e2e/assets/expect_scripts/rust_svelte_with_tests_and_ii.exp b/e2e/assets/expect_scripts/rust_svelte_with_tests_and_ii.exp
@@ -0,0 +1,21 @@
+#!/usr/bin/expect -df
+
+match_max 100000
+set timeout 30
+
+spawn dfx new e2e_project
+expect "Select a backend language:"
+# down arrow, Rust should be option 2
+send "\033\[B"
+send "\r"
+
+expect "Select a frontend framework:"
+# no down arrow, Svelte should be option 1
+send "\r"
+# first and third, should be II and frontend tests respectively
+expect "Add extra features"
+send " "
+send "\033\[B\033\[B"
+send " "
+send "\r"
+expect eof
diff --git a/e2e/tests-dfx/assetscanister.bash b/e2e/tests-dfx/assetscanister.bash
@@ -5,7 +5,7 @@ load ../utils/_
 setup() {
   standard_setup
 
-  dfx_new
+  dfx_new_assets
 }
 
 teardown() {
@@ -91,6 +91,7 @@ check_permission_failure() {
   PREPARE_PRINCIPAL=$(dfx identity get-principal --identity prepare)
   COMMIT_PRINCIPAL=$(dfx identity get-principal --identity commit)
 
+  rm src/e2e_project_frontend/assets/.ic-assets.json5
   install_asset assetscanister
   # Prep for a DeleteAsset operation
   echo "to-be-deleted" >src/e2e_project_frontend/assets/to-be-deleted.txt
@@ -196,6 +197,7 @@ check_permission_failure() {
   PREPARE_PRINCIPAL=$(dfx identity get-principal --identity prepare)
   COMMIT_PRINCIPAL=$(dfx identity get-principal --identity commit)
 
+  rm src/e2e_project_frontend/assets/.ic-assets.json5
   install_asset assetscanister
   dfx_start
   mkdir tmp
@@ -1626,6 +1628,7 @@ WARN: {
 }
 
 @test "asset configuration via .ic-assets.json5 - pretty printing when deploying" {
+  rm src/e2e_project_frontend/assets/.ic-assets.json5
   install_asset assetscanister
 
   dfx_start
@@ -1668,6 +1671,7 @@ WARN: {
 }
 
 @test "syncs asset properties when redeploying" {
+  rm src/e2e_project_frontend/assets/.ic-assets.json5
   install_asset assetscanister
   dfx_start
   assert_command dfx deploy

diff --git a/e2e/tests-dfx/bitcoin.bash b/e2e/tests-dfx/bitcoin.bash
@@ -37,7 +37,7 @@ set_local_network_bitcoin_enabled() {
 }
 
 @test "dfx restarts replica when ic-btc-adapter restarts" {
-  dfx_new hello
+  dfx_new_assets hello
   dfx_start --enable-bitcoin
 
   install_asset greet

diff --git a/e2e/tests-dfx/build_granular.bash b/e2e/tests-dfx/build_granular.bash
@@ -5,7 +5,7 @@ load ../utils/_
 setup() {
   standard_setup
 
-  dfx_new
+  dfx_new_assets
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/canister_http.bash b/e2e/tests-dfx/canister_http.bash
@@ -46,7 +46,7 @@ set_shared_local_network_canister_http_empty() {
 }
 
 @test "dfx restarts replica when ic-https-outcalls-adapter restarts" {
-  dfx_new hello
+  dfx_new_assets hello
   dfx_start
 
   install_asset greet

diff --git a/e2e/tests-dfx/create.bash b/e2e/tests-dfx/create.bash
@@ -6,7 +6,7 @@ load ../utils/cycles-ledger
 setup() {
   standard_setup
 
-  dfx_new
+  dfx_new_assets
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/deploy.bash b/e2e/tests-dfx/deploy.bash
@@ -6,7 +6,7 @@ load ../utils/cycles-ledger
 setup() {
   standard_setup
 
-  dfx_new hello
+  dfx_new_assets hello
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/dotenv.bash b/e2e/tests-dfx/dotenv.bash
@@ -5,7 +5,7 @@ load ../utils/_
 setup() {
   standard_setup
 
-  dfx_new
+  dfx_new_assets
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/error_diagnosis.bash b/e2e/tests-dfx/error_diagnosis.bash
@@ -12,20 +12,6 @@ teardown() {
   standard_teardown
 }
 
-@test "Duplicate assets in dist/ from src/" {
-  dfx_new_frontend hello
-  install_asset greet
-  dfx_start
-  assert_command dfx deploy
-
-  # simulate previous deploy with CopyPlugin step
-  cp src/hello_frontend/assets/* dist/hello_frontend/
-
-  assert_command_fail dfx deploy
-  assert_contains "Remove the CopyPlugin step from webpack.config.js"
-  assert_contains "Delete all files from the dist/ directory"
-}
-
 @test "HTTP 403 has a full diagnosis" {
   dfx_new hello
   install_asset greet

diff --git a/e2e/tests-dfx/frontend.bash b/e2e/tests-dfx/frontend.bash
@@ -65,8 +65,8 @@ teardown() {
   assert_match "Connection refused"
 }
 
-@test "dfx uses .ic-assets.json file provided in src/__project_name__frontend/src" {
-  echo '[{"match": "*", "headers": {"x-key": "x-value"}}]' > src/e2e_project_frontend/src/.ic-assets.json
+@test "dfx uses .ic-assets.json file provided in src/__project_name__frontend/assets" {
+  echo '[{"match": "*", "headers": {"x-key": "x-value"}}]' > src/e2e_project_frontend/assets/.ic-assets.json5
 
   dfx_start
   dfx canister create --all
@@ -77,14 +77,14 @@ teardown() {
   PORT=$(get_webserver_port)
   assert_command curl -vv http://localhost:"$PORT"/?canisterId="$ID"
   assert_match "< x-key: x-value"
-  assert_command curl -vv http://localhost:"$PORT"/index.js?canisterId="$ID"
+  assert_command curl -vv http://localhost:"$PORT"/favicon.ico?canisterId="$ID"
   assert_match "< x-key: x-value"
 }
 
 @test "dfx uses a custom build command if one is provided" {
-  jq '.canisters.e2e_project_frontend.source = ["dist/e2e_project_frontend/"]' dfx.json | sponge dfx.json
-  jq '.canisters.e2e_project_frontend.build = ["npm run custom-build"]' dfx.json | sponge dfx.json
-  jq '.scripts["custom-build"] = "mkdir -p ./dist/e2e_project_frontend/assets/ && cp -r ./src/e2e_project_frontend/assets/* ./dist/e2e_project_frontend"' package.json | sponge package.json
+  jq '.canisters.e2e_project_frontend.source = ["src/e2e_project_frontend/dist2"]' dfx.json | sponge dfx.json
+  jq '.canisters.e2e_project_frontend.build = ["npm run custom-build --workspace e2e_project_frontend"]' dfx.json | sponge dfx.json
+  jq '.scripts["custom-build"] = "npm run build && mkdir -p ./dist2/ && cp -r ./dist/* ./dist2"' src/e2e_project_frontend/package.json | sponge src/e2e_project_frontend/package.json
 
   dfx_start
   dfx canister create --all
@@ -94,6 +94,6 @@ teardown() {
   ID=$(dfx canister id e2e_project_frontend)
   PORT=$(get_webserver_port)
 
-  assert_command curl -vv http://localhost:"$PORT"/sample-asset.txt?canisterId="$ID"
-  assert_match "This is a sample asset!"
+  assert_command curl -vv http://localhost:"$PORT"/index.html?canisterId="$ID"
+  assert_match "IC Hello Starter"
 }
diff --git a/e2e/tests-dfx/identity.bash b/e2e/tests-dfx/identity.bash
@@ -5,7 +5,7 @@ load ../utils/_
 setup() {
   standard_setup
 
-  dfx_new
+  dfx_new_assets
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/install.bash b/e2e/tests-dfx/install.bash
@@ -5,7 +5,7 @@ load ../utils/_
 setup() {
   standard_setup
 
-  dfx_new
+  dfx_new_assets
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/metadata.bash b/e2e/tests-dfx/metadata.bash
@@ -186,7 +186,7 @@ teardown() {
 }
 
 @test "asset canister provides candid:service metadata" {
-  dfx_new hello
+  dfx_new_assets hello
   dfx_start
 
   assert_command dfx deploy

diff --git a/e2e/tests-dfx/mode_reinstall.bash b/e2e/tests-dfx/mode_reinstall.bash
@@ -5,7 +5,7 @@ load ../utils/_
 setup() {
   standard_setup
 
-  dfx_new hello
+  dfx_new_assets hello
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/new.bash b/e2e/tests-dfx/new.bash
@@ -7,6 +7,7 @@ setup() {
 }
 
 teardown() {
+  dfx_stop
   standard_teardown
 }
 
@@ -51,9 +52,34 @@ teardown() {
   assert_eq "motoko"
 }
 
-@test "dfx new always emits sample-asset.txt" {
-  assert_command dfx new e2e_frontend --frontend
-  assert_file_exists e2e_frontend/src/e2e_frontend_frontend/assets/sample-asset.txt
-  assert_command dfx new e2e_no_frontend --no-frontend
-  assert_file_exists e2e_no_frontend/src/e2e_no_frontend_frontend/assets/sample-asset.txt
+@test "frontend templates apply successfully" {
+  for frontend in sveltekit vue react vanilla simple-assets none; do
+    assert_command dfx new e2e_${frontend/-/_} --frontend $frontend
+  done
+  assert_file_not_exists e2e_none/src/e2e_none_frontend
+}
+
+@test "frontend templates pass the frontend tests" {
+  dfx_start
+  for frontend in sveltekit vue react vanilla; do
+    assert_command dfx new e2e_$frontend --frontend $frontend --extras frontend-tests
+    pushd e2e_$frontend
+    assert_command dfx deploy
+    assert_command npm test --workspaces
+    popd
+  done
+}
+
+@test "backend templates" {
+  for backend in motoko rust kybra azle; do
+    assert_command dfx new e2e_$backend --type $backend --no-frontend
+  done
+}
+
+@test "interactive template selection" {
+  assert_command "${BATS_TEST_DIRNAME}/../assets/expect_scripts/rust_svelte_with_tests_and_ii.exp"
+  assert_file_exists e2e_project/Cargo.toml
+  assert_file_exists e2e_project/src/e2e_project_frontend/src/routes/+page.svelte
+  assert_file_exists e2e_project/src/e2e_project_frontend/src/setupTests.js
+  assert_command jq .canisters.internet_identity e2e_project/dfx.json
 }
diff --git a/e2e/tests-dfx/playground.bash b/e2e/tests-dfx/playground.bash
@@ -5,7 +5,7 @@ load ../utils/_
 setup() {
   standard_setup
   setup_playground
-  dfx_new hello
+  dfx_new_assets hello
 }
 
 teardown() {

diff --git a/e2e/tests-dfx/start.bash b/e2e/tests-dfx/start.bash
@@ -130,7 +130,7 @@ teardown() {
 }
 
 @test "dfx restarts icx-proxy" {
-  dfx_new hello
+  dfx_new_assets hello
   dfx_start
 
   install_asset greet
@@ -155,7 +155,7 @@ teardown() {
 }
 
 @test "dfx restarts icx-proxy when the replica restarts" {
-  dfx_new hello
+  dfx_new_assets hello
   dfx_start
 
   install_asset greet

diff --git a/e2e/tests-dfx/usage_env.bash b/e2e/tests-dfx/usage_env.bash
@@ -24,7 +24,7 @@ teardown() {
   #cache
   # create a new project to install dfx cache
   assert_command_fail ls "$DFX_CACHE_ROOT/.cache/dfinity/versions"
-  dfx new hello
+  dfx new hello --no-frontend
   assert_command ls "$DFX_CACHE_ROOT/.cache/dfinity/versions"
   assert_command_fail ls "$HOME/.cache/dfinity/versions"
   rm -rf hello
@@ -42,7 +42,7 @@ teardown() {
     #cache
     # create a new project to install dfx cache
     assert_command_fail ls "$HOME/.cache/dfinity/versions"
-    dfx new hello
+    dfx new hello --no-frontend
     assert_command ls "$HOME/.cache/dfinity/versions"
     rm -rf hello
   )