Skip to content

Commit

Permalink
docs: update stacks.js pages (#616)
Browse files Browse the repository at this point in the history
* docs: update stacks.js pages

* fix: update style

* chore: remove faulty link

* chore: adjust mlc

* chore: update mlc

* chore: fix mlc

---------

Co-authored-by: janniks <janniks@users.noreply.github.com>
  • Loading branch information
janniks and janniks authored Feb 26, 2024
1 parent 67c4122 commit 5e6c87c
Show file tree
Hide file tree
Showing 9 changed files with 78 additions and 67 deletions.
8 changes: 8 additions & 0 deletions .github/mlc_config.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,14 @@
},
{
"pattern": "identity.foundation"
},
{
"pattern": "learn-the-basics",
"comment": "// todo: remove once https://github.com/hirosystems/docs/pull/616 is merged"
},
{
"pattern": "stackoverflow.com/questions/tagged/stacks\\-blockchain\\+or\\+clarity\\-lang",
"comment": "// Returns a 403 sometimes"
}
],
"replacementPatterns": [
Expand Down
40 changes: 25 additions & 15 deletions docs/stacks.js/connect.md → docs/stacks.js/connect.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Overview
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Stacks Connect

Expand All @@ -16,34 +15,45 @@ title: Overview
</div>

Stacks Connect is a frontend library that allows developers to build Stacks-ready web applications.
Kickstart your next project with Stacks Connect templates with React, Vue, and more [→ Stacks.js Starters](/stacksjs-starters)

## Features
What are the main things you can do with Stacks Connect?

- 📸 Prompt a user to sign transactions with their Stacks wallet
- 🛂 Provide the web-app with the user's Stacks and Bitcoin addresses

## Getting Started with Stacks Connect
## Start from a template with Stacks Connect included

Get started [from a frontend template](/stacksjs-starters), by running the following command:

```sh
npm create stacks
```

- [Add the dependency](#1-add-the-dependency)
- [Creating `AppConfig` and `UserSession`](#2-creating-appconfig-and-usersession)
- [Interacting with the wallet](#3-interacting-with-the-wallet)
- ["Connect" aka authentication (`showConnect`)](#connect-aka-authentication-showconnect)
- [Sending STX (`openSTXTransfer`)](#sending-stx-openstxtransfer)
- [Calling Smart-Contracts (`openContractCall`)](#calling-smart-contracts-opencontractcall)
- [Sending transactions with post-conditions (`openContractCall`)](#sending-transactions-with-post-conditions-opencontractcall)
- [Post-Condition Modes](#post-condition-modes)
After you have your project set up, you can start using Stacks Connect. Jump ahead to [Interacting with the wallet](#3-interacting-with-the-wallet) to see more code examples.

---

## Manually add Stacks Connect to your project

### 1. Add the dependency

Add the `@stacks/connect` dependency to your project using your favorite package manager.
_Some options below_



<Tabs><TabItem value="npm" label="npm">
```sh
npm install @stacks/connect
```
</TabItem><TabItem value="pnpm" label="pnpm">
```sh
pnpm install @stacks/connect
```
</TabItem><TabItem value="yarn" label="yarn">
```sh
yarn add @stacks/connect
```
</TabItem></Tabs>

### 2. Creating `AppConfig` and `UserSession`

Expand Down
4 changes: 2 additions & 2 deletions docs/stacks.js/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar_label: FAQs

# Stacks.js FAQs

#### What are Post Conditions? How do Post Conditions work?
### What are Post Conditions? How do Post Conditions work?

In computer programming, a post-condition is a condition (or a predicate) that must always be true just after the execution of some section of code or after an operation. And on Stacks, transactions are secured by post-conditions. Thus, if a post-condition check fails on a Clarity smart contract then the entire transaction is reverted.

Expand All @@ -14,7 +14,7 @@ Post-conditions are less a part of Clarity (the language), but more a part of tr
Users could send the otherwise-identical transaction (Example: contract-call, executing a function on the blockchain) with OR without different post-conditions, in allow OR deny mode.
The PCs are managed by the user/wallet/app that's creating the tx; so they are a bit different from the other "safety" features of clarity (Example: asserts, try, https://book.clarity-lang.org/ch06-00-control-flow.html)

#### How to fix the BigInt support when using Stacks.js?
### How to fix the BigInt support when using Stacks.js?

BigInt support is available in most modern browsers, but some bundlers try to optimize them incorrectly. If you are targeting browsers that are too outdated, building an application with Stacks.js dependencies might fail.
To solve this set your project `browserslist` to the following [package.json](https://github.com/hirosystems/stacks.js-starters/blob/efb93261b59494f4eb34a7cb5db5d82a84bd3b7c/templates/template-react/package.json#L34-L40).
16 changes: 7 additions & 9 deletions docs/stacks.js/index.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
---
sidebar_label: Overview
---

# Stacks.js Overview

<div className="gap-3 flex flex-wrap mb-6">
Expand Down Expand Up @@ -32,14 +28,16 @@ It's a collection of various JavaScript libraries allowing developers to interac

<!-- todo: add color -->

## Getting started

<div class="subSections my-8">
<a href="/stacks.js/connect">
<div class="subSectionTitle"><h3>Stacks Connect 🌐</h3><span>→</span></div>
<div class="subSectionTitle"><h3>Build a web-app</h3><span>→</span></div>
<p>Build Stacks-ready web applications</p>
</a>
<a href="/stacks.js/getting-started">
<div class="subSectionTitle"><h3>Getting Started</h3><span>→</span></div>
<p>Explore all that Stacks.js has to offer</p>
<div class="subSectionTitle"><h3>Build a service</h3><span>→</span></div>
<p>Dive deeper and build on Stacks</p>
</a>
</div>

Expand All @@ -52,7 +50,7 @@ For example, a web app that allows users to interact with the Stacks blockchain
Most users interact via their favorite Stacks wallet.
Developers can build web apps, which prompt the user for an action (e.g. sign a transaction), and then the wallet will handle the rest.
The wallet will act in the security, and best interest of the user, and the user will be able to review the transaction before signing.
[Read more](./connect.md)
[Read more](/stacks.js/connect)

### 🔑 With Private Key Access

Expand All @@ -63,4 +61,4 @@ Developers can build simple scripts and tools intended for "offline" use.
Users may use the Stacks.js CLI directly to send a transaction.
Backends may need to automate signing without direct user interaction.
In these cases, developers can use the same libraries used by Stacks wallets for account handling and transaction signing.
[Read more](./installing.md)
[Read more](/stacks.js/learn-the-basics)
Original file line number Diff line number Diff line change
@@ -1,12 +1,8 @@
---
sidebar_label: Getting Started
---
# Learning the Stacks.js Basics

# Getting Started with Stacks.js
<div class="bg-neutral-200 rounded-lg text-sm text-neutral-700 p-3">Looking to building Stacks-ready web applications? [Read more on Stacks Connect](/stacks.js/connect)</div>

import StacksjsStartersNote from '../includes/\_stacks.js-starters-note.mdx';

<StacksjsStartersNote/>
<div class="mb-9"></div>

To introduce the different functionality offered by Stacks.js, we'll walk through a few examples and concepts important to building on the Stacks blockchain.

Expand Down Expand Up @@ -83,9 +79,6 @@ openSTXTransfer({
});
```

<!-- todo -->
<!-- [Read more](./connect.md) about transaction signing with Stacks Connect. -->

### Using a private key 🔑

For full manual transaction signing, we need to provide the sender's private key.
Expand Down
9 changes: 0 additions & 9 deletions docs/stacks.js/troubleshooting.md

This file was deleted.

25 changes: 7 additions & 18 deletions sidebars/stacks-js.js
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,13 @@ module.exports = [
},
{
type: 'doc',
label: 'Getting Started',
id: 'stacks.js/getting-started',
label: 'Learn the basics',
id: 'stacks.js/learn-the-basics',
},
{
type: 'doc',
label: 'FAQs',
id: 'stacks.js/faq',
},
{
type: 'html',
Expand Down Expand Up @@ -65,20 +70,4 @@ module.exports = [
label: 'Integrate Stacking',
id: 'stacks.js/guides/how-to-integrate-stacking', // TODO: merge both stacking guides
},
{
type: 'html',
value: 'Other',
className: 'section-title',
defaultStyle: true,
},
{
type: 'doc',
label: 'FAQs',
id: 'stacks.js/faq',
},
{
type: 'doc',
label: 'Troubleshooting',
id: 'stacks.js/troubleshooting',
},
];
25 changes: 21 additions & 4 deletions src/css/custom.css
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@

@font-face {
font-family: 'Aeonik Fono';
src: url('https://alphaassets.hiro.so/AeonikFono-Regular.woff2') format('woff2'),
src:
url('https://alphaassets.hiro.so/AeonikFono-Regular.woff2') format('woff2'),
url('https://alphaassets.hiro.so/AeonikFono-Regular.woff') format('woff');
font-weight: normal;
font-style: normal;
Expand All @@ -29,7 +30,8 @@

@font-face {
font-family: 'AeonikMono-Regular';
src: url('https://alphaassets.hiro.so/AeonikMono-Regular.woff2') format('woff2'),
src:
url('https://alphaassets.hiro.so/AeonikMono-Regular.woff2') format('woff2'),
url('https://alphaassets.hiro.so/AeonikMono-Regular.woff') format('woff');
font-weight: normal;
font-style: normal;
Expand Down Expand Up @@ -97,6 +99,9 @@
--ifm-code-font-size: 81.25%;
--ifm-alert-border-left-width: 0px;

--ifm-tabs-padding-vertical: 4px;
--ifm-tabs-padding-horizontal: 8px;

--aa-primary-color-rgb: var(--ifm-color-primary-lighter);
}

Expand Down Expand Up @@ -124,7 +129,10 @@ body {
}

p {
font-family: 'Inter var', system-ui, -apple-system;
font-family:
'Inter var',
system-ui,
-apple-system;
}

[data-theme='dark'] table,
Expand Down Expand Up @@ -488,6 +496,15 @@ a.menu__link.menu__link--sublist.menu__link--sublist-caret::after {
}
}

/* CODE TABS ================================================================ */
.tabs-container ul {
font-size: small;
}

.tabs-container .margin-top--md {
margin-top: 0 !important;
}

/* CONTENT MARKDOWN ELEMENTS ================================================ */
/* Prefixed with `Hiro` */

Expand All @@ -509,7 +526,7 @@ a.HiroLink {
font-size: 0.875rem;
line-height: 1.25rem;
transition: color 0.15s ease;
background-color: ;
background-color:;
}

a.HiroLinkExternal {
Expand Down
5 changes: 5 additions & 0 deletions vercel.json
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,11 @@
"source": "/tutorials/overview",
"destination": "https://docs.hiro.so/tutorials",
"permanent": true
},
{
"source": "/stacks.js/getting-started",
"destination": "https://docs.hiro.so/stacks.js",
"permanent": false
}
]
}

0 comments on commit 5e6c87c

Please sign in to comment.