@ -53,47 +53,13 @@ Finally, make sure you have [created at least one Blockstack ID]({{ site.baseurl
## Use npm to install Yeoman and the Blockstack App Generator
## Use npm to install Yeoman and the Blockstack App Generator
You use `npm` to install Yeoman. Yeoman is a generic scaffolding system that
{% include scaffolding.md %}
helps users rapidly start new projects and streamline the maintenance of
existing projects.
1. Use `npm` to install Yeoman and the Blockstack generator
```bash
npm install -g yo generator-blockstack
```
You can use the generator to create starter applications for these frameworks:
<tableclass="uk-table">
<tr>
<th>Framework</th>
<th>Use this command to install</th>
</tr>
<tr>
<td>Plain Javascript</td>
<td><code> blockstack</code></td>
</tr>
<tr>
<td>Webpack</td>
<td><code> blockstack:webpack</code></td>
</tr>
<tr>
<td>React</td>
<td><code> blockstack:react</code></td>
</tr>
<tr>
<td>Vue</td>
<td><code> blockstack:vue</code></td>
</tr>
</table>
For this example, you will use plain Javascript.
## Generate an initial Blockstack application
## Generate an initial Blockstack application
In this section, you build an initial React.js application called `hello-world-tutorial`.
In this section, you build an initial React.js application called `hello-world-tutorial`. For this example, you will use plain Javascript scaffolding.
1. Create the `hello-world-tutorial` directory.
1. Create the `hello-world-tutorial` directory.
@ -328,37 +294,6 @@ user home screens. The contents are very simple:
Keep it as is or fill it in with new information that describes your app.
Keep it as is or fill it in with new information that describes your app.
### Save your application code
### Congratulations you are all done!
Complete the tutorial by storing your app code on GitHub. Before you begin, make sure you have a GitHub account and have configured your environment to use it.
1. Initialize the application code as a Git repo.
```bash
git init
```
2. Add and commit all of the files:
```bash
git add . && git commit -m "first commit"
```
3. In GitHub, create a `hello-blockstack` repository.
4. Back in your terminal window, add a remote for GitHub.
5. Push your new code to the master branch of the remote repo:
```
git push origin master
```
You're done! You just built your first Blockstack app and shipped the code.
You're done! You just built your first Blockstack app and shipped the code. You're well on your way to becoming a Blockstack app legend. If you want to save your code, you can upload it to GitHub or similar code repository.
You're well on your way to becoming a Blockstack app legend.
In this tutorial, you build the code for and run a single-page application (SPA)
In this tutorial, you build the code for and run a single-page application (SPA)
with Blockstack and Vue.js. Once the application is running, you take a tour
with Blockstack and React. Once the application is running, you take a tour
through the applications’ Blockstack functionality. You’ll learn how it manages
through the applications’ Blockstack functionality. You’ll learn how it manages
authentiation using a Blockstack ID and how it stores information associated
authentcation using a Blockstack ID and how it stores information associated
with that ID using Blockstack Storage (Gaia).
with that ID using Blockstack Storage (Gaia).
* TOC
* TOC
@ -17,11 +17,9 @@ with that ID using Blockstack Storage (Gaia).
{% include note.html content="On macOS, Blockstack requires macOS High Sierra. This tutorial was written on macOS High Sierra 10.13.4. If you use a Windows or Linux system, you can still follow along. However, you will need to \"translate\" appropriately for your operating system. Additionally, this tutorial assumes you are accessing the Blockstack Browser web application via Chrome. The application you build will also work with a local installation and/or with browsers other than Chrome. " %}
{% include note.html content="On macOS, Blockstack requires macOS High Sierra. This tutorial was written on macOS High Sierra 10.13.4. If you use a Windows or Linux system, you can still follow along. However, you will need to \"translate\" appropriately for your operating system. Additionally, this tutorial assumes you are accessing the Blockstack Browser web application via Chrome. The application you build will also work with a local installation and/or with browsers other than Chrome. " %}
If you prefer a video, you can view <ahref="https://www.youtube.com/embed/oyvg-h0obFw"target="\_blank">a video of the tutorial</a>.
## Before you begin
## Before you begin
The application you build is a Vue.js application that is completely decentralized and server-less. While not strictly required to follow along, basic familiarity with Vue.js is helpful. When complete, the app is capable of the following:
The application you build is a React application that is completely decentralized and server-less. While not strictly required to follow along, basic familiarity with React is helpful. When complete, the app is capable of the following:
* authenticating users using Blockstack
* authenticating users using Blockstack
* posting new statuses
* posting new statuses
@ -31,20 +29,10 @@ The application you build is a Vue.js application that is completely decentraliz
For this tutorial, you will use the following tools:
For this tutorial, you will use the following tools:
* your workstation's command line
* your workstation's command line
* `git` to clone the tutorial code
* `npm` to manage dependencies and scripts
* `npm` to manage dependencies and scripts
The basic identity and storage services are provided by blockstack.js. To test the application, you need to have already registered a Blockstack ID.
The basic identity and storage services are provided by blockstack.js. To test the application, you need to have already registered a Blockstack ID.
### Verify you have git installed
This tutorial uses `git` to clone the tutorial code. Verify you have installed `git` using the `which` command to verify.
```bash
$ which git
/usr/local/bin/npm
```
### Verify you have npm installed
### Verify you have npm installed
The tutorial relies on the `npm` dependency manager. Before you begin, verify you have installed `npm` using the `which` command to verify.
The tutorial relies on the `npm` dependency manager. Before you begin, verify you have installed `npm` using the `which` command to verify.
@ -53,6 +41,7 @@ The tutorial relies on the `npm` dependency manager. Before you begin, verify yo
$ which npm
$ which npm
/usr/local/bin/npm
/usr/local/bin/npm
```
```
If you don’t find `npm` in your system, [install it](https://www.npmjs.com/get-npm).
If you don’t find `npm` in your system, [install it](https://www.npmjs.com/get-npm).
### Make sure you have a Blockstack ID
### Make sure you have a Blockstack ID
@ -62,10 +51,7 @@ You’ll use this ID to interact with the application.
## Task 1: Install the code and retrieve the dependencies
## Task 1: Install the code and retrieve the dependencies
You can clone the source code with `git` or [download and unzip the code from
You can clone the source code with `git` or [download and unzip the code from the repository](https://github.com/blockstack/blockstack-todos/archive/master.zip). These instructions assume you are cloning.
@ -80,6 +66,9 @@ These instructions assume you are cloning.
$ cd blockstack-todos
$ cd blockstack-todos
```
```
If you downloaded the zip file, the contents unzip into a `blockstack-todos-master` directory.
3. Use `npm` to install the dependencies.
3. Use `npm` to install the dependencies.
@ -87,15 +76,14 @@ These instructions assume you are cloning.
$ npm install
$ npm install
```
```
The Todo application has a basic Vue.js structure. There are several configuration files but the central programming files are in the `src` directory:
The Todo application has a basic React structure. There are several configuration files but the central programming files are in the `src/components` directory:
| File | Description |
| File | Description |
|-----------------|-------------|
|-----------------|-------------|
| `main.js` | Application initialization. |
| `index.js` | Application initialization. |
| `App.vue ` | Code for handling the `authResponse`. |
| `components/App.js ` | Code for handling the `authResponse`. |
| `components/Landing.vue ` | Code for the initial sign on page. |
| `components/Signin.js ` | Code for the initial sign on page. |
| `components/Dashboard.vue` | Application data storage and user sign out. |
| `components/Profile.js` | Application data storage and user sign out. |
## Task 2: Sign into the application
## Task 2: Sign into the application
@ -113,22 +101,23 @@ The example application runs in a node server on your local host. In the this se
2. Start the application in your local environment.
2. Start the application in your local environment.
```bash
```bash
$ npm run serve
$ npm start
```
```
You should see output similar to the following:
```bash
You should see output similar to the following:
98% after emitting CopyPlugin s
DONE Compiled successfully in 5854ms 7:34:28 PM
```bash
Compiled successfully!
You can now view bs-todo in the browser.
App running at:
http://127.0.0.1:3000/
- Local: http://localhost:8080/
- Network: http://192.168.0.12:8080/
Note that the development build is not optimized.
Note that the development build is not optimized.
To create a production build, run npm run build.
To create a production build, use npm run build.
```
```
2. Open your local browser to the `http://localhost:8080` URL.
2. Open your local browser to the `http://localhost:3000` URL.
You should see a simple application:
You should see a simple application:
@ -193,45 +182,50 @@ in and sign out is handled in each of these files:
| File | Description |
| File | Description |
|-----------------|-------------|
|-----------------|-------------|
| `App.vue ` | Handles the `authResponse`. |
| `components/App.js ` | Code for handling the `authResponse`. |
| `Landing.vue ` | Generates the `authRequest`. |
| `components/Signin.js ` | Code for the initial sign on page. |
| `Dashboard.vue` | Handles sign out. |
| `components/Profile.js` | Application data storage and user sign out. |
The `src/components/Landing.vue` code configures an `AppConfig` object and then uses this to create a `UserSession`. Then, the application calls a [`redirectToSignIn()`](https://blockstack.github.io/blockstack.js#redirectToSignIn) function which generates the `authRequest` and redirects the user to the Blockstack authenticator:
The `src/components/App.js` code configures an `AppConfig` object and then uses this to create a `UserSession`. Then, the application calls a [`redirectToSignIn()`](https://blockstack.github.io/blockstack.js#redirectToSignIn) function which generates the `authRequest` and redirects the user to the Blockstack authenticator:
```js
```js
signIn () {
...
const appConfig = new this.blockstack.AppConfig(['store_write', 'publish_data'])
const userSession = new UserSession({ appConfig })
const UserSession = new this.blockstack.UserSession({ appConfig: appConfig })
UserSession.redirectToSignIn()
export default class App extends Component {
}
handleSignIn(e) {
e.preventDefault();
userSession.redirectToSignIn();
}
...
```
```
Once the user authenticates, the application handles the `authResponse` in the `src/App.vue` file. :
Once the user authenticates, the application handles the `authResponse` in the `src/components/Profile.js` file. :
this.user = new this.blockstack.Person(this.userData.profile)
//if (!userData.username) {
this.user.username = this.userData.username
// throw new Error('This app requires a username.')
} else if (UserSession.isSignInPending()) {
//}
UserSession.handlePendingSignIn()
window.location = window.location.origin;
.then((userData) => {
});
window.location = window.location.origin
})
}
}
},
}
...
```
```
If [`blockstack.isUserSignedIn()`](https://blockstack.github.io/blockstack.js/#isusersignedin) is true, the user was previously signed in so Blockstack pulls the data from the browser and uses it in our application. If the check on [`blockstack.UserSession.isSignInPending()`](https://blockstack.github.io/blockstack.js/#issigninpending) is true, a previous `authResponse` was sent to the application but hasn't been processed yet. The `handlePendingSignIn()` function processes any pending sign in.
If [`isUserSignedIn()`](https://blockstack.github.io/blockstack.js/#isusersignedin) is true, the user was previously signed in so Blockstack pulls the data from the browser and uses it in our application. If the check on [`UserSession.isSignInPending()`](https://blockstack.github.io/blockstack.js/#issigninpending) is true, a previous `authResponse` was sent to the application but hasn't been processed yet. The `handlePendingSignIn()` function processes any pending sign in.
Signout is handled in `src/components/Dashboard.vue`.
@ -245,101 +239,38 @@ Now, trying adding a few items to the todo list. For example, try making a list
Each list is immediately stored in the Gaia Hub linked to your Blockstack ID.
Each list is immediately stored in the Gaia Hub linked to your Blockstack ID.
For more information about the Gaia hub, [see the overview in this documentation]({{ site.baseurl }}/storage/overview.html#). You can fetch the `todos.json`
For more information about the Gaia hub, [see the overview in this documentation]({{ site.baseurl }}/storage/overview.html#). Now that you have seen the application in action, dig into how it works.
file you just added by opening the Javascript console and running the following
You should see a JSON with the todos you just added:
```json
[
{
"id":2,
"text":"Software package manager secured by the blockchain",
"completed":false
},
{
"id":1,
"text":"Mutable torrents with human readable names",
"completed":false
},
{
"id":0,
"text":"Decentralized twitter",
"completed":false
}
]
```
Add another todo and check it off. When you fetch the newly generated file
using the Javascript console, the results reflect your change. Look for `"completed":true`:
```json
[
{
"id":3,
"text":"Blockstack Todo",
"completed":true
},
{
"id":2,
"text":"Software package manager secured by the blockchain",
"completed":false
},
...
]
```
Now that you have seen the application in action, dig into how it works.
## Task 7: Implement storage
## Task 7: Implement storage
Go to the underlying `blockstack-todo` code you cloned or downloaded. The
Go to the underlying `blockstack-todo` code you cloned or downloaded. The application interactions with your Gaia Hub originate in the `src/components/Profile.js` file. First, examine where the changes to the Todos are processed in the `Profile.js` file.
application interactions with your Gaia Hub originate in the
`src/components/Dashboard.vue` file. First, examine where the changes to the
The code needs to read the Todo items from the storage with the [`getFile()`](https://blockstack.github.io/blockstack.js/#getfile) method which returns a promise:
The `todos` data is retrieved from the promise. By default, the `getFile()` decrypts data for you. For more information on the available options, see the <ahref="https://blockstack.github.io/blockstack.js/interfaces/getfileoptions.html"taraget="_blank">the blockstack.js</a> library for details on the `GetFileOptions` interface.
The `todos` JSON object is passed in and the
During the creation of a `todos`, a JSON object is passed in and the [`putFile()`](https://blockstack.github.io/blockstack.js/#putfile) method to store it in a Gaia Hub. By default, `putFile()` encrypts data when it stores it.
method to store it in a Gaia Hub. By default, `putFile()` encrypts data when it stores it.
The code needs to read the Todo items from the storage with the [`blockstack.UserSession.getFile()`](https://blockstack.github.io/blockstack.js/#getfile) method which returns a promise:
The `todos` data is retrieved from the promise. By default, the `getFile()` decrypts data for you. For more information on the available options, see the <ahref="https://blockstack.github.io/blockstack.js/interfaces/getfileoptions.html"taraget="_blank">the blockstack.js</a> library for details on the `GetFileOptions` interface.
You use `npm` to install Yeoman and Blockstack App Generator. Yeoman is a generic scaffolding system that helps users rapidly start new projects and streamline the maintenance of existing projects.
1. Use `npm` to install Yeoman and the Blockstack generator
```bash
npm install -g yo generator-blockstack
```
You can use the generator to create scaffolding for a starter application. The generator can create scaffoling for any of these frameworks:
<tableclass="uk-table">
<tr>
<th>Framework</th>
<th>Use this command to install</th>
</tr>
<tr>
<td>Plain Javascript</td>
<td><code> blockstack</code></td>
</tr>
<tr>
<td>Webpack</td>
<td><code> blockstack:webpack</code></td>
</tr>
<tr>
<td>React</td>
<td><code> blockstack:react</code></td>
</tr>
<tr>
<td>Vue</td>
<td><code> blockstack:vue</code></td>
</tr>
</table>
For example, to install a Vue scaffolding, use the `npm create yo blockstack:vue` command.
Moxiegirl
5 years ago
GitHub
