Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 39 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,29 @@ If there are verbosity flags available, please include those to offer as much in

When opening a pull request, please use the typical open-source flow of forking the desired repository and opening a pull request from your forked repository. (More information on [how to contribute](https://docs.near.org/docs/community/contribute/how-to-contribute).)

To make changes to `create-near-app` itself:

* clone the repository (Windows users, [use `git clone -c core.symlinks=true`](https://stackoverflow.com/a/42137273/249801))
* in your terminal, enter one of the folders inside `templates`, such as `templates/frontend/next-app`
* now you can run `pnpm install` to install dependencies and `pnpm run dev` to run the local development server, just like you can in a new app created with `create-near-app`


## About commit messages

`create-near-app` uses semantic versioning and auto-generates nice release notes & a changelog all based off of the commits. We do this by enforcing [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). In general the pattern mostly looks like this:

type(scope?): subject #scope is optional; multiple scopes are supported (current delimiter options: "/", "\" and ",")

Real world examples can look like this:

chore: run tests with GitHub Actions

fix(server): send cors headers

feat(blog): add comment section

If your change should show up in release notes as a feature, use `feat:`. If it should show up as a fix, use `fix:`. Otherwise, you probably want `refactor:` or `chore:`. [More info](https://github.com/conventional-changelog/commitlint/#what-is-commitlint)

## Testing

Please note that for technical contributions, NEAR runs a battery of continuous integration tools and tests for each pull request.
Expand All @@ -21,6 +44,21 @@ It's encouraged to write unit tests on new features. Many NEAR repositories have

For example, a repository might have `npm test` available. It's a good idea to run tests locally before submitting a pull request, as these will be caught during the CI process.

### Thank you
## Deploy `create-near-app`

If you want to deploy a new version, you will need two prerequisites:

1. Get publish-access to [the NPM package](https://www.npmjs.com/package/near-api-js)
2. Get write-access to [the GitHub repository](https://github.com/near/near-api-js)
3. Obtain a [personal access token](https://gitlab.com/profile/personal_access_tokens) (it only needs the "repo" scope).
4. Make sure the token is [available as an environment variable](https://github.com/release-it/release-it/blob/master/docs/environment-variables.md) called `GITHUB_TOKEN`

Then run one script:

npm run release

Or just `release-it`

## Thank you

NEAR values all contributors to the projects in the ecosystem and invites public discussion on the tech and vision. Please feel free to join the conversation using the links offered at [near.help](https://near.help).
62 changes: 16 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Create NEAR App

[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/nearprotocol/create-near-app)
[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/nearprotocol/create-near-app)

Quickly build apps backed by the [NEAR](https://near.org) blockchain

Expand All @@ -20,7 +20,7 @@ To create a new NEAR project run this and follow interactive prompts:
Follow the instructions in the README.md in the project you just created! 🚀


### Contracts
## Contracts
You can create contracts written in:
- `Javascript`
- `Rust`
Expand All @@ -31,7 +31,7 @@ We strongly recommend you to follow our [smart contract quickstart](https://docs

For testing we use a sandboxed environment. You can write the tests in JavaScript or Rust.

### WebApps
## WebApps

You can create a web application in:

Expand All @@ -47,13 +47,22 @@ We strongly recommend you to follow our [web app quickstart](https://docs.near.o

## Using CLI arguments to run `create-near-app`

This CLI supports arguments to skip interactive prompts:
This CLI supports arguments to skip interactive prompts

For a Web App:
```shell
npx create-near-app
<project-name>
--frontend next-app|next-page|none
--contract js|rs|none
--install
```

For a Smart Contract:

```shell
npx create-near-app
<project-name>
--contract ts|rs|none
--install
```

Expand All @@ -65,48 +74,9 @@ When using arguments, all arguments are required, except for `--install`.

Check out our [documentation](https://docs.near.org) or chat with us on [Discord](http://near.chat). We'd love to hear from you!

## Contributing

## Contributing to `create-near-app`

To make changes to `create-near-app` itself:

* clone the repository (Windows users, [use `git clone -c core.symlinks=true`](https://stackoverflow.com/a/42137273/249801))
* in your terminal, enter one of the folders inside `templates`, such as `templates/frontend/next-app`
* now you can run `pnpm install` to install dependencies and `pnpm run dev` to run the local development server, just like you can in a new app created with `create-near-app`


#### About commit messages

`create-near-app` uses semantic versioning and auto-generates nice release notes & a changelog all based off of the commits. We do this by enforcing [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). In general the pattern mostly looks like this:

type(scope?): subject #scope is optional; multiple scopes are supported (current delimiter options: "/", "\" and ",")

Real world examples can look like this:

chore: run tests with GitHub Actions

fix(server): send cors headers

feat(blog): add comment section

If your change should show up in release notes as a feature, use `feat:`. If it should show up as a fix, use `fix:`. Otherwise, you probably want `refactor:` or `chore:`. [More info](https://github.com/conventional-changelog/commitlint/#what-is-commitlint)


#### Deploy `create-near-app`

If you want to deploy a new version, you will need two prerequisites:

1. Get publish-access to [the NPM package](https://www.npmjs.com/package/near-api-js)
2. Get write-access to [the GitHub repository](https://github.com/near/near-api-js)
3. Obtain a [personal access token](https://gitlab.com/profile/personal_access_tokens) (it only needs the "repo" scope).
4. Make sure the token is [available as an environment variable](https://github.com/release-it/release-it/blob/master/docs/environment-variables.md) called `GITHUB_TOKEN`

Then run one script:

npm run release

Or just `release-it`

We welcome contributions! Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) file for detailed guidelines on how to contribute to this project.

## License

Expand Down
69 changes: 43 additions & 26 deletions templates/contracts/ts/README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,24 @@
# Hello NEAR Contract
# Quick Start: Create, Build, and Deploy a NEAR Smart Contract in TypeScript

The smart contract exposes two methods to enable storing and retrieving a greeting in the NEAR network.
## Prerequisites

1. **Node.js( >= 16) and npm**: Ensure they are installed.
2. **NEAR CLI**: Install globally:

```
npm install -g near-cli
```
3. **NEAR Testnet Account**: Create one if you haven't already.

## 1: Set Up Your Project
```
npx create-near-app
```
## 2: Write Your Smart Contract
Create the contract in `/src`
```ts
import { NearBindgen, near, call, view } from 'near-sdk-js';

@NearBindgen({})
class HelloNear {
greeting: string = "Hello";
Expand All @@ -13,44 +29,43 @@ class HelloNear {
}

@call // This method changes the state, for which it cost gas
set_greeting({ greeting }: { greeting: string }): void {
set_greeting({ greeting }: { greeting: string }):
void {
// Record a log permanently to the blockchain!
near.log(`Saving greeting ${greeting}`);
this.greeting = greeting;
}
}
```

<br />

# Quickstart
## 3: Build the Contract
```
npx near-sdk-js build <path_to_contract>
```

1. Make sure you have installed [node.js](https://nodejs.org/en/download/package-manager/) >= 16.
2. Install the [`NEAR CLI`](https://github.com/near/near-cli#setup)
## 4: Deploy the Contract

<br />
#### Create and Account and Deploy
```sh
# Create a new account pre-funded by a faucet & deploy
near create-account <accountId> --useFaucet
near deploy <accountId> <route_to_wasm>

## 1. Build and Test the Contract
You can automatically compile and test the contract by running:

```bash
npm run build
# Get the account name
cat ./neardev/dev-account
```

<br />
#### Deploy in an Existing Account

## 2. Create an Account and Deploy the Contract
You can create a new account and deploy the contract by running:
```sh
# login into your account
near login

```bash
near create-account <your-account.testnet> --useFaucet
near deploy <your-account.testnet> build/release/hello_near.wasm
# deploy the contract
near deploy <accountId> <route_to_wasm>
```

<br />


## 3. Retrieve the Greeting
## 5. Retrieve the Greeting

`get_greeting` is a read-only method (aka `view` method).

Expand All @@ -63,7 +78,7 @@ near view <your-account.testnet> get_greeting

<br />

## 4. Store a New Greeting
## 6. Store a New Greeting
`set_greeting` changes the contract's state, for which it is a `call` method.

`Call` methods can only be invoked using a NEAR account, since the account needs to pay GAS for the transaction.
Expand All @@ -80,4 +95,6 @@ near call <your-account.testnet> set_greeting '{"greeting":"howdy"}' --accountId
near login
```

and then use the logged account to sign the transaction: `--accountId <another-account>`.
and then use the logged account to sign the transaction: `--accountId <another-account>`.

[Smart Contracts quickstart docs](https://docs.near.org/build/smart-contracts/quickstart)
1 change: 1 addition & 0 deletions templates/contracts/ts/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"test": "$npm_execpath run build && ava -- ./build/hello_near.wasm"
},
"dependencies": {
"near-contract-standards": "2.0.0",
"near-sdk-js": "1.0.0"
},
"devDependencies": {
Expand Down
Loading