Skip to content

Commit 3474707

Browse files
fxgstfxgst
authored
chore: Update for Ninja Examples (#1118)
- add instructions how to add an ICP Ninja project - remove Motoko playground referernces - add open in ICP Ninja button - rename workflow to specifically mention Ninja, remove Makefile option to avoid confusion - update READMEs - move .devcontainer.json into .devcontainer folder
1 parent 62efb28 commit 3474707

File tree

43 files changed

+287
-151
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+287
-151
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Contributing
22

3+
> For ICP Ninja: check [NINJA_CONTRIBUTING.md](./../NINJA_CONTRIBUTING.md) for how to contribute a project to ICP Ninja.
4+
35
Thank you for your interest in contributing to example apps for the Internet Computer.
46
By participating in this project, you agree to abide by our [Code of Conduct](./CODE_OF_CONDUCT.md).
57

.github/workflows/examples_pr_checks.yml renamed to .github/workflows/ninja_pr_checks.yml

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
1-
name: Test examples
1+
name: Test ICP Ninja Examples
22

33
on:
44
pull_request:
55
branches:
66
- master
77

88
concurrency:
9-
group: examples-pr-checks-${{ github.workflow }}-${{ github.ref }}
9+
group: ninja-pr-checks-${{ github.workflow }}-${{ github.ref }}
1010
cancel-in-progress: true
1111

1212
jobs:
13-
check-example-changes:
13+
check-ninja-example-changes:
1414
name: Filter projects
1515
runs-on: ubuntu-22.04
1616
outputs:
@@ -74,12 +74,12 @@ jobs:
7474
7575
build-examples:
7676
name: Build
77-
needs: check-example-changes
78-
if: needs.check-example-changes.outputs.has_examples == 'true'
77+
needs: check-ninja-example-changes
78+
if: needs.check-ninja-example-changes.outputs.has_examples == 'true'
7979
runs-on: ubuntu-22.04
8080
container: ghcr.io/dfinity/icp-dev-env-slim:17
8181
strategy:
82-
matrix: ${{ fromJson(needs.check-example-changes.outputs.matrix) }}
82+
matrix: ${{ fromJson(needs.check-ninja-example-changes.outputs.matrix) }}
8383

8484
steps:
8585
- name: Checkout
@@ -93,9 +93,4 @@ jobs:
9393

9494
- name: Build project
9595
working-directory: ${{ matrix.example.path }}
96-
run: |
97-
if [ -f "Makefile" ]; then
98-
make test
99-
else
100-
dfx deploy
101-
fi
96+
run: dfx deploy

‎ADDING_AN_EXAMPLE.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# How to Add a New Example
1+
# How to add a new example
2+
3+
> For ICP Ninja: check [NINJA_CONTRIBUTING.md](./NINJA_CONTRIBUTING.md) for how to contribute a project to ICP Ninja.
24
35
Ideally, each example should come with both Rust and Motoko implementations,
46
implementing the same Candid interface (and, ideally, semantics).

‎NINJA_CONTRIBUTING.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Contributing a project to ICP Ninja
2+
3+
We recommend to build your example directly within ICP Ninja, such that it starts out with the correct tooling, structure and configs.
4+
If you do that, your project will naturally be in the correct format and can be easily added to ICP Ninja.
5+
Once the example is done, you can download the source files from ICP Ninja.
6+
Alternatively, you can start with an existing Ninja project from this repo (see CODEOWNERS file for Ninja examples) and modify it.
7+
8+
Ideally, your project should have a frontend and backend.
9+
10+
### Where to place your example
11+
* `/motoko` for a Motoko project
12+
* `/rust` for a Rust project
13+
* `/hosting` for a frontend-only project
14+
15+
### Compilation requirements
16+
* Make sure the project compiles and runs with `dfx deploy` inside the latest `ghcr.io/dfinity/icp-dev-env-slim` container.
17+
* Make sure `npm run dev` works and the canister can be called through the browser (if applicable).
18+
* Make sure II login works (if applicable).
19+
* If you use Rust, make sure the project has `ic_cdk::export_candid!();` in the `lib.rs` file, such that the Candid interface can be auto derived.
20+
* If you use Motoko, use Mops as the package manager.
21+
22+
### Frontend tooling requirements
23+
* React
24+
* Vite for the build system
25+
* Tailwind CSS for styling (recommended), or plain CSS
26+
27+
## Preparing the PR
28+
1. Add your project in the `CODEOWNERS` file, with your team plus `@dfinity/ninja-devs` as reviewers.
29+
2. Add your project to the matrix in `.github/workflows/ninja_pr_checks.yml` to run PR tests.
30+
3. Add a `README.md` file, copy the `BUILD.md` and `devcontainer.json` files.
31+
32+
## Submit a PR to ICP Ninja
33+
1. Add your newly added project to `frontend/public/projects.json`
34+
2. Bump the commit hash in `submodules/examples` to a commit hash after your PR has been merged into the examples repo.
35+
* ask the Ninja team or AI to give you a beautiful image for your project
36+
37+
## Templates
38+
39+
### Recommended `dfx.json` for a Rust canister:
40+
41+
```json
42+
{
43+
"canisters": {
44+
"backend": {
45+
"candid": "backend/backend.did",
46+
"type": "custom",
47+
"shrink": true,
48+
"gzip": true,
49+
"wasm": "target/wasm32-unknown-unknown/release/backend.wasm",
50+
"build": [
51+
"cargo build --target wasm32-unknown-unknown --release -p backend",
52+
"candid-extractor target/wasm32-unknown-unknown/release/backend.wasm > backend/backend.did"
53+
],
54+
"metadata": [
55+
{
56+
"name": "candid:service"
57+
}
58+
]
59+
}
60+
},
61+
"output_env_file": ".env"
62+
}
63+
```
64+
65+
### Recommended `dfx.json` for a Motoko canister:
66+
67+
```json
68+
{
69+
"canisters": {
70+
"backend": {
71+
"main": "backend/app.mo",
72+
"type": "motoko",
73+
"args": "--enhanced-orthogonal-persistence"
74+
},
75+
},
76+
"output_env_file": ".env",
77+
"defaults": {
78+
"build": {
79+
"packtool": "mops sources"
80+
}
81+
}
82+
}
83+
84+
```
85+
86+
### Recommended `dfx.json` for a frontend/asset canister:
87+
88+
```json
89+
{
90+
"canisters": {
91+
"frontend": {
92+
"dependencies": ["backend"],
93+
"frontend": {
94+
"entrypoint": "frontend/index.html"
95+
},
96+
"source": ["frontend/dist"],
97+
"type": "assets"
98+
}
99+
},
100+
"output_env_file": ".env"
101+
}
102+
```
103+
104+
### Recommended `vite.config.js`
105+
106+
```js
107+
import react from '@vitejs/plugin-react';
108+
import { defineConfig } from 'vite';
109+
import { fileURLToPath, URL } from 'url';
110+
import environment from 'vite-plugin-environment';
111+
112+
export default defineConfig({
113+
base: './',
114+
plugins: [react(), environment('all', { prefix: 'CANISTER_' }), environment('all', { prefix: 'DFX_' })],
115+
envDir: '../',
116+
define: {
117+
'process.env': process.env
118+
},
119+
optimizeDeps: {
120+
esbuildOptions: {
121+
define: {
122+
global: 'globalThis'
123+
}
124+
}
125+
},
126+
resolve: {
127+
alias: [
128+
{
129+
find: 'declarations',
130+
replacement: fileURLToPath(new URL('../src/declarations', import.meta.url))
131+
}
132+
]
133+
},
134+
server: {
135+
proxy: {
136+
'/api': {
137+
target: 'http://127.0.0.1:4943',
138+
changeOrigin: true
139+
}
140+
},
141+
host: '127.0.0.1'
142+
}
143+
});
144+
```

‎README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ Additional frontend samples can be found in the following folders:
2424

2525
## Deploying samples
2626

27+
### ICP Ninja
28+
29+
You can open and deploy examples with [ICP Ninja](https://icp.ninja/), a web-based tool that allows you to create and manage Internet Computer projects without downloading any tools or setting up a local environment.
30+
31+
To contribute an example that will be featured on ICP Ninja, check out the [NINJA_CONTRIBUTING.md](./NINJA_CONTRIBUTING.md) file.
32+
2733
### GitHub Codespaces or Gitpod
2834

2935
This repo can be opened in a web-based developer environment such as [GitHub Codespaces](https://github.com/codespaces) or [Gitpod](https://www.gitpod.io/), allowing you to edit and deploy the sample projects without downloading any tools or setting up a local environment.
@@ -32,10 +38,6 @@ This repo can be opened in a web-based developer environment such as [GitHub Cod
3238

3339
[Get started with Gitpod](https://internetcomputer.org/docs/current/developer-docs/developer-tools/ide/gitpod).
3440

35-
### Motoko Playground
36-
37-
Motoko Playground is a web-based developer environment for Motoko projects. To use Motoko Playground, navigate to the [playground UI](https://m7sm4-2iaaa-aaaab-qabra-cai.ic0.app/) and select a template to get started, or start a new project.
38-
3941
### dfx
4042

4143
dfx is a command-line tool used to create, deploy. and manage projects on ICP. To download and use dfx with this examples repo, run the following commands locally (macOS/Linux systems):

hosting/my_crypto_blog/devcontainer.json renamed to hosting/my_crypto_blog/.devcontainer/devcontainer.json

File renamed without changes.

‎hosting/my_crypto_blog/README.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,17 @@
1-
# My crypto blog
1+
# My Crypto Blog
22

33
This frontend-only asset canister allows you to serve static files without a backend canister.
44
Asset canisters can be used to serve static frontend files, such as HTML, CSS, and JavaScript files, to users through a web browser.
55

6-
## Project structure
6+
## Deploying from ICP Ninja
77

8-
The `/frontend` folder contains web assets for the application's user interface. The user interface is written using the React framework.
8+
When viewing this project in ICP Ninja, you can deploy it directly to the mainnet for free by clicking "Deploy" in the upper right corner. Open this project in ICP Ninja:
99

10-
## Deploying from ICP Ninja
10+
[![](https://icp.ninja/assets/open.svg)](https://icp.ninja/i?url=https://github.com/dfinity/examples/hosting/my_crypto_blog)
1111

12-
When viewing this project in ICP Ninja, you can deploy it directly to the mainnet for free by clicking "Deploy" in the upper right corner.
13-
To open this project in ICP Ninja, click [here](https://icp.ninja/i?url=https://github.com/dfinity/examples/tree/master/hosting/my_crypto_blog).
12+
## Project structure
1413

15-
To **download** or **reset** the project files, click the menu option next to the deploy button.
14+
The `/frontend` folder contains web assets for the application's user interface. The user interface is written using the React framework.
1615

1716
## Build and deploy from the command-line
1817

hosting/react/devcontainer.json renamed to hosting/react/.devcontainer/devcontainer.json

File renamed without changes.

‎hosting/react/README.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,17 @@
1-
# Basic frontend
1+
# Basic Frontend
22

33
This frontend-only asset canister allows you to serve static files without a backend canister.
44
Asset canisters can be used to serve static frontend files, such as HTML, CSS, and JavaScript files, to users through a web browser.
55

6-
## Project structure
6+
## Deploying from ICP Ninja
77

8-
The `/frontend` folder contains web assets for the application's user interface. The user interface is written using the React framework.
8+
When viewing this project in ICP Ninja, you can deploy it directly to the mainnet for free by clicking "Deploy" in the upper right corner. Open this project in ICP Ninja:
99

10-
## Deploying from ICP Ninja
10+
[![](https://icp.ninja/assets/open.svg)](https://icp.ninja/i?url=https://github.com/dfinity/examples/hosting/react)
1111

12-
When viewing this project in ICP Ninja, you can deploy it directly to the mainnet for free by clicking "Deploy" in the upper right corner.
13-
To open this project in ICP Ninja, click [here](https://icp.ninja/i?url=https://github.com/dfinity/examples/tree/master/hosting/react).
12+
## Project structure
1413

15-
To **download** or **reset** the project files, click the menu option next to the deploy button.
14+
The `/frontend` folder contains web assets for the application's user interface. The user interface is written using the React framework.
1615

1716
## Build and deploy from the command-line
1817

motoko/backend_only/devcontainer.json renamed to motoko/backend_only/.devcontainer/devcontainer.json

File renamed without changes.

0 commit comments

Comments
 (0)