diff --git a/.github/mlc_config.json b/.github/mlc_config.json index 94485d089..43956f418 100644 --- a/.github/mlc_config.json +++ b/.github/mlc_config.json @@ -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": [ diff --git a/docs/stacks.js/connect.md b/docs/stacks.js/connect.mdx similarity index 88% rename from docs/stacks.js/connect.md rename to docs/stacks.js/connect.mdx index ea3185df2..043edf051 100644 --- a/docs/stacks.js/connect.md +++ b/docs/stacks.js/connect.mdx @@ -1,6 +1,5 @@ ---- -title: Overview ---- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Stacks Connect @@ -16,34 +15,45 @@ title: Overview 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_ + + + ```sh npm install @stacks/connect +``` + +```sh pnpm install @stacks/connect +``` + +```sh yarn add @stacks/connect ``` + ### 2. Creating `AppConfig` and `UserSession` diff --git a/docs/stacks.js/faq.md b/docs/stacks.js/faq.md index 9fbadc84e..c5f1c4e96 100644 --- a/docs/stacks.js/faq.md +++ b/docs/stacks.js/faq.md @@ -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. @@ -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). diff --git a/docs/stacks.js/index.md b/docs/stacks.js/index.md index 370c1b1aa..2e143b1da 100644 --- a/docs/stacks.js/index.md +++ b/docs/stacks.js/index.md @@ -1,7 +1,3 @@ ---- -sidebar_label: Overview ---- - # Stacks.js Overview
@@ -32,14 +28,16 @@ It's a collection of various JavaScript libraries allowing developers to interac +## Getting started +
-

Stacks Connect 🌐

+

Build a web-app

Build Stacks-ready web applications

-

Getting Started

-

Explore all that Stacks.js has to offer

+

Build a service

+

Dive deeper and build on Stacks

@@ -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 @@ -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) diff --git a/docs/stacks.js/getting-started.md b/docs/stacks.js/learn-the-basics.md similarity index 96% rename from docs/stacks.js/getting-started.md rename to docs/stacks.js/learn-the-basics.md index 86b02805b..1e3e98ef6 100644 --- a/docs/stacks.js/getting-started.md +++ b/docs/stacks.js/learn-the-basics.md @@ -1,12 +1,8 @@ ---- -sidebar_label: Getting Started ---- +# Learning the Stacks.js Basics -# Getting Started with Stacks.js +
Looking to building Stacks-ready web applications? [Read more on Stacks Connect](/stacks.js/connect)
-import StacksjsStartersNote from '../includes/\_stacks.js-starters-note.mdx'; - - +
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. @@ -83,9 +79,6 @@ openSTXTransfer({ }); ``` - - - ### Using a private key 🔑 For full manual transaction signing, we need to provide the sender's private key. diff --git a/docs/stacks.js/troubleshooting.md b/docs/stacks.js/troubleshooting.md deleted file mode 100644 index b723ee840..000000000 --- a/docs/stacks.js/troubleshooting.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Troubleshooting ---- - -## Common Pitfall: regenerator-runtime - -If using @stacks/connect with vite, rollup, svelte, or vue, a package `regenerator-runtime` needs to be manually added to build the project successfully. - -`npm install --save-dev regenerator-runtime.` diff --git a/sidebars/stacks-js.js b/sidebars/stacks-js.js index dbe209367..81e0f0203 100644 --- a/sidebars/stacks-js.js +++ b/sidebars/stacks-js.js @@ -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', @@ -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', - }, ]; diff --git a/src/css/custom.css b/src/css/custom.css index bfe2bbc53..67665c403 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -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; @@ -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; @@ -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); } @@ -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, @@ -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` */ @@ -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 { diff --git a/vercel.json b/vercel.json index 434b12d96..b56d70176 100644 --- a/vercel.json +++ b/vercel.json @@ -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 } ] }