5. Crear un frontend Hello World
En los ejemplos anteriores, invocamos los contratos utilizando Stellar CLI, y en esta última parte de la guía vamos a crear una aplicación web que interactúa con el contrato Hello World a través de enlaces de TypeScript.
Este ejemplo muestra una manera de crear una vinculación entre un contrato y un frontend. Para una guía más completa sobre frontends de Dapp, consulta la documentación Desarrollar un frontend para Dapp. Para herramientas que te ayuden a comenzar rápidamente con contratos inteligentes integrados en un entorno frontend funcional, aprende más sobre Scaffold Stellar.
Inicializar una cadena de herramientas frontend desde cero
Puedes crear un dapp Stellar con cualquier cadena de herramientas para frontend o integrarlo en cualquier aplicación de stack completo existente. Para este tutorial, vamos a utilizar Astro. Astro trabaja con React, Vue, Svelte, cualquier otra biblioteca de interfaz de usuario o sin biblioteca de interfaz de usuario en absoluto. En este tutorial, no estamos utilizando una biblioteca de interfaz de usuario. Las partes específicas del contrato inteligente de este tutorial serán similares sin importar qué cadena de herramientas para frontend utilices.
Si eres nuevo en el frontend, no te preocupes. No profundizaremos demasiado. Pero será útil para ti ver y experimentar el proceso de desarrollo de frontend utilizado por aplicaciones de contratos inteligentes. Cubriré los aspectos relevantes de JavaScript y Astro, pero enseñar todo el desarrollo de frontend y Astro está más allá del alcance de este tutorial.
Vamos a comenzar.
Vas a necesitar Node.js v20 o superior. Si aún no lo has hecho, instálalo ahora.
Queremos crear un proyecto Astro con el contrato Hello World de las lecciones anteriores integrado. Para hacerlo, instalamos el proyecto Astro por defecto:
npm create astro@latest
Este proyecto tiene la siguiente estructura de directorios.
extra-escape
├── astro.config.mjs
├── package-lock.json
├── package.json
├── packages
├── public
├── README.md
├── src
│ ├── assets
│ │ ├── astro.svg
│ │ └── background.svg
│ ├── components
│ │ └── Welcome.astro
│ ├── layouts
│ │ └── Layout.astro
│ └── pages
│ └── index.astro
└── tsconfig.json
Como ya hemos desplegado estos contratos con alias, podemos reutilizar los archivos de ID de contrato generados copiándolos del directorio soroban-hello-world/.stellar en este proyecto:
cp -R ../.stellar/ .stellar
Generar un paquete NPM para el contrato Hello World
Antes de abrir los nuevos archivos de frontend, generemos un paquete NPM para el contrato Hello World. Esta es nuestra forma sugerida de interactuar con contratos desde frontends. Estas bibliotecas generadas funcionan con cualquier proyecto JavaScript (no con una interfaz específica como React) y facilitan trabajar con algunos de los aspectos más complejos de los contratos inteligentes en Stellar, como la codificación de XDR.
Esto va a utilizar el comando CLI stellar contract bindings typescript:
stellar contract bindings typescript \
--network testnet \
--contract-id hello_world \
--output-dir packages/hello_world
¡Ten en cuenta que pudimos utilizar el alias del contrato, hello_world, en lugar del ID del contrato!
El enlace se creará como un paquete NPM en el directorio packages/hello_world como se especifica en el comando CLI. Necesitaremos compilar el paquete de enlaces, ya que (en su estado inicial) el paquete es mayormente tipos y stubs de TypeScript para las diversas funciones del contrato.
cd packages/hello_world
npm install
npm run build
cd ../..
Intentamos mantener el código en estas bibliotecas generadas legible, así que ve y explora. Abre el nuevo directorio packages/hello_world en tu editor. Si has construido o contribuido a proyectos de Node, todo te parecerá familiar. Verás un archivo package.json, un directorio src, un tsconfig.json, e incluso un README.
Llamar al contrato desde el frontend
Ahora abramos src/pages/index.astro y utilicemos el enlace para llamar a la función del contrato hello con un argumento.
El proyecto Astro por defecto consiste en una página (pages/index.astro) y un componente de bienvenida (component/Welcome.astro), y no necesitamos ninguno de esos códigos. Reemplaza el código de pages/index.astro con este código (el componente de bienvenida no será necesario):
---
import * as Client from './packages/hello_world';
const contract = new Client.Client({
...Client.networks.testnet,
rpcUrl: 'https://soroban-testnet.stellar.org:443'
});
const { result } = await contract.hello({to: "Devs!"});
const greeting = result.join(" ");
---
<h1>{greeting}</h1>
Primero importamos la biblioteca de enlaces, y luego necesitamos definir un cliente de contrato que podamos usar para invocar la función del contrato que desplegamos en testnet en un paso anterior.
La función del contrato hello() se invoca de forma sincrónica con el argumento {to: "Devs!"} y la respuesta esperada es un arreglo que consiste en "Hello" y "Devs!". Unimos el arreglo de resultados y la constante greeting debería ahora contener el texto Hello Devs!
Bajando a la sección HTML ahora queremos mostrar el texto greeting en el navegador. ¡Veámoslo en acción! Inicia el servidor de desarrollo:
npm run dev
Y abre localhost:4321 en tu navegador. ¡Deberías ver el saludo del contrato!
Puedes intentar actualizar el argumento a { to: 'Stellar' }. Cuando guardes el archivo, la página se actualizará automáticamente.
Cuando inicies el servidor de desarrollo con npm run dev, verás una salida similar en tu terminal a cuando ejecutaste npm run init. Esto es porque el script dev en package.json está configurado para ejecutar npm run init y astro dev, para que puedas asegurarte de que tu contrato desplegado y tu paquete NPM generado estén siempre sincronizados. Si quieres simplemente iniciar el servidor de desarrollo sin el script initialize.js, puedes ejecutar npm run astro dev.
Usar Scaffold Stellar para desarrollar dapps rápidamente
Scaffold Stellar es un kit de herramientas para desarrolladores para construir aplicaciones descentralizadas y contratos inteligentes en la blockchain Stellar, integrado con una aplicación frontend.
Conseguir un conjunto funcional de contratos inteligentes y un frontend se puede hacer en sólo unos pocos pasos con Scaffold Stellar. Este tutorial te mostrará cómo crear un nuevo proyecto Scaffold Stellar.
Si deseas usar contratos inteligentes existentes en un proyecto Scaffold Stellar, ¡solo tienes que copiarlos a la carpeta contracts/ en la raíz de tu proyecto!
- Instalar el CLI de Scaffold Stellar
Como ya tienes instalado el CLI de Stellar, tienes todo lo necesario para instalar Scaffold Stellar:
cargo binstall stellar-scaffold-cli
Recomendamos usar binstall para instalaciones más rápidas, o usar cargo install --locked stellar-scaffold-cli. Scaffold Stellar es un plugin del CLI de Stellar, por lo que usarás stellar scaffold desde la línea de comandos.
- Inicializar un proyecto Scaffold Stellar nuevo
stellar scaffold init <my-project>
Scaffold Stellar es un plugin del CLI de Stellar, así que ejecutarás comandos como stellar scaffold <comando>. init inicializa un proyecto Stellar Scaffold nuevo en la ruta proporcionada.
- Instalar dependencias de Node y configurar variables de entorno
Asegúrate de tener Node.js instalado, y ejecuta:
cd <my-project> # make sure you're in your new project's directory
npm install # install frontend dependencies
cp .env.example .env # copies the example frontend environment variable file to your own copy
- ¡Inicia tu app en modo desarrollo!
npm start # or npm run dev
Este comando realiza dos tareas simultáneamente: ejecuta stellar scaffold watch --build-clients, que compila tus contratos inteligentes, actualizándolos a medida que los modificas, desplegándolos en tu cadena Stellar local (¡asegúrate de que Docker esté corriendo!), y configura todos estos ajustes vía tu archivo environments.toml en la carpeta raíz de tu proyecto.
La segunda tarea que ejecuta es vite, una popular herramienta de compilación JavaScript que compila y observa tu frontend React para detectar cambios.
Después de unos momentos de compilación, podrás ver tu app funcionando en localhost:5173!
Aprende más sobre Scaffold Stellar.