Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update cli command in getting started guide and closes #1138 #1162

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+16 −21
Open

Update cli command in getting started guide and closes #1138 #1162

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7f181f2
Update cli command in getting started guide and closes #1138
janewang Jan 6, 2025
e506db0
Remove frontend-template
janewang Jan 6, 2025
0a5bdc8
Remove --frontend-template
janewang Jan 6, 2025
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
11 changes: 4 additions & 7 deletions docs/build/apps/dapp-frontend.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,13 @@ Let's get started.

You're going to need [Node.js](https://nodejs.org/en/download/package-manager/) v18.14.1 or greater. If you haven't yet, install it now.

We want to initialize our current project as an Astro project. To do this, we can again turn to the `stellar contract init` command, which has a `--frontend-template` flag that allows us to pass the url of a frontend template repository. As we learned in [Storing Data](../smart-contracts/getting-started/storing-data.mdx#adding-the-increment-contract), `stellar contract init` will not overwrite existing files, and is safe to use to add to an existing project.

From our `soroban-hello-world` directory, run the following command to add the Astro template files.
We want to initialize our current project as an Astro project. From our `soroban-hello-world` directory, run the following command to add the Astro template files.

```sh
stellar contract init ./ \
--frontend-template https://github.com/stellar/soroban-astro-template
git clone [email protected]:stellar/soroban-template-astro.git
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this will clone the template repo's files into a new soroban-template-astro directory, inside soroban-hello-world. in order to use these template files, i think we'd need to instruct the user to copy them into the root of the soroban-hello-world project.

```

This will add the following to your project, which we'll go over in more detail below.
This will clone the following to your project, which we'll go over in more detail below.

```bash
├── CONTRIBUTING.md
Expand Down Expand Up @@ -495,4 +492,4 @@ At this point, you've seen a full end-to-end example of building a contract on S

- See more complex example contracts in the [Example Contracts](../smart-contracts/example-contracts/README.mdx) section.
- Learn more about the [internal architecture and design](../../learn/encyclopedia/contract-development/README.mdx) of Soroban.
- Learn how to find other templates for use with `--frontend-template`, other than [stellar/soroban-template-astro](https://github.com/stellar/soroban-astro-template), and how to build your own: [Develop contract initialization frontend templates](../guides/dapps/soroban-contract-init-template.mdx)
- Learn how to find other templates other than [stellar/soroban-template-astro](https://github.com/stellar/soroban-astro-template), and how to build your own: [Develop contract initialization frontend templates](../guides/dapps/soroban-contract-init-template.mdx)
20 changes: 9 additions & 11 deletions docs/build/guides/dapps/soroban-contract-init-template.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
---
title: Develop contract initialization frontend templates
title: Develop contract with frontend templates
description: Understand, find, and create your own frontend templates for use with Stellar CLI's `stellar contract init` command
---

<head>
<title>Develop contract initialization frontend templates</title>
<title>Develop contract witn frontend templates</title>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<title>Develop contract witn frontend templates</title>
<title>Develop contract with frontend templates</title>

<meta charSet="utf-8" />
<meta
property="og:title"
content="Develop contract initialization frontend templates"
content="Develop contract with frontend templates"
/>
<meta
property="og:description"
content="Understand, find, and create your own frontend templates for use with Stellar CLI's `stellar contract init` command"
/>
</head>

This guide picks up where [Build a Dapp Frontend](../../apps/dapp-frontend.mdx) left off, taking a deeper look at the `--frontend-template` used there. From there, we'll:
This guide picks up where [Build a Dapp Frontend](../../apps/dapp-frontend.mdx) left off. From there, we'll:

1. Search GitHub for other Soroban templates
1. Build our own simple template
Expand All @@ -29,11 +29,11 @@ The official template maintained by Stellar Development Foundation (SDF), as use

(You may wonder why it makes this unpopular choice. A fair question! The team wanted to balance actual utility with broad approachability. Not everyone learning Stellar and Soroban is familiar with React, or any other UI library. It also demonstrates that core Soroban libraries all work with any JavaScript project.)

But note that the CLI's `contract init` command was made to work with _any_ frontend template. It need not even live on GitHub! Simply pass another valid git URL to the command, and it will clone that instead of the official repository:
But note that the CLI's `contract init` command was made to work with a specific set of templates. To use other templates, we will clone other templates from repository:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
But note that the CLI's `contract init` command was made to work with a specific set of templates. To use other templates, we will clone other templates from repository:
To use other templates, we will clone them from their repositories:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change just removes the contract init reference, since the fe templates are independent of init now.


```bash
# the following is NOT a valid git repository, and will not work 😄
stellar contract init my-new-project --frontend-template https://whatever.cool/project/you/want
git clone https://whatever.cool/project/you/want
```

So how can you find other valid frontend templates?
Expand All @@ -54,9 +54,7 @@ This will be easier than you might imagine. There are a few gotchas, but overall

### But first, how are these projects organized?

When you run `stellar contract init`, it _always_ includes a Rust/Cargo project, with a `Cargo.toml` that defines a workspace, and workspace members located in a `contracts` folder. At a minimum, there's one contract, `contracts/hello_world`, but you can get more by using `--with-example`.

Separately, you _may_ include a `--frontend-template`. Frontend templates so far have all been Node projects, which have a `package.json` in the root. In the final composite project, the Node project and Rust project live side-by-side, and the frontend template expects the Rust project to be there. It expects a `contracts` folder with one or more subfolders, and it expects a `target` directory with all the Rust build artifacts.
When you run `stellar contract init`, it _always_ includes a Rust/Cargo project, with a `Cargo.toml` that defines a workspace, and workspace members located in a `contracts` folder. At a minimum, there's one contract, `contracts/hello_world`, but you can get more by using `--name`.

So keep that in mind. We're making a fairly simple Node project, and telling it about our Soroban stuff, like the `contracts` folder.

Expand Down Expand Up @@ -99,7 +97,7 @@ So this script:
4. _binds_ contracts — that is, it creates NPM projects for each deployed contract by running `stellar contract bindings typescript`
5. imports the contracts for straightforward use in the rest of your project

Remember that it needs to do this all _in a contract-agnostic way_. That is, the `--frontend-template` choice is separate from the `--with-example` choice. The frontend template doesn't know what contracts it might find! But it needs to build, deploy, bind, and import whatever's there.
Remember that it needs to do this all _in a contract-agnostic way_. The frontend template doesn't know what contracts it might find! But it needs to build, deploy, bind, and import whatever's there.

So this script does that.

Expand Down Expand Up @@ -215,7 +213,7 @@ stellar network container start local
Now we can run `contract init`. Let's include one extra contract. Then we'll run the `dev` script (which, remember, will run the `initialize.js` script first):

```bash
stellar contract init . --with-example increment
stellar contract init . --name increment
npm run dev
```

Expand Down
6 changes: 3 additions & 3 deletions docs/build/smart-contracts/getting-started/storing-data.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,12 @@ This tutorial assumes that you've already completed the previous steps in Gettin

## Adding the increment contract

The `stellar contract init` command allows us to initialize a new project with any of the example contracts from the [soroban-examples](https://github.com/stellar/soroban-examples) repo, using the `--with-example` (or `-w`) flag.
The `stellar contract init` command allows us to initialize a new project with any of the example contracts from the [soroban-examples](https://github.com/stellar/soroban-examples) repo, using the `--name` flag, to specify a new contract's name.

It will not overwrite existing files, so we can also use this command to add a new contract to an existing project. Run the command again with a `--with-example` flag to add an `increment` contract to our project. From inside our `soroban-hello-world` directory, run:
It will not overwrite existing files unless we explicily pass in `--ovewrite` flag. Run the command with a `--name` flag to add an `increment` contract to our project. From inside our `soroban-hello-world` directory, run:

```sh
stellar contract init ./ --with-example increment
stellar contract init . --name increment
Copy link
Contributor

@elizabethengelman elizabethengelman Jan 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At the moment this command copies the contents of the hello-world contract from the binary, and renames the directory as increment.

I think that the only way to get the contracts from soroban-examples we still need to use --with-example for now.

The deprecation notice about --with-examples (below) directs the user to clone examples from the repo, perhaps this should be changed to do that instead?

error: invalid value 'increment' for '--with-example <WITH_EXAMPLE>': This argument has been removed and will be not be recognized by the future versions of CLI: Adding examples via cli is no longer supported. You can still clone examples from the repo https://github.com/stellar/soroban-examples

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another idea would be to use stellar contract init . --name increment still and then copy the increment lib.rs and test.rs files over into the new files that are created. but that may be confusing. 🤔

```

This will create a new `contracts/increment` directory with the following files:
Expand Down
Loading