From 445ef4b06e580c92bdfe71d47394f1516e96d527 Mon Sep 17 00:00:00 2001 From: Ali Serag Date: Wed, 22 Apr 2026 18:03:51 -0500 Subject: [PATCH] docs: add TL;DR, FAQ, and GEO enhancements for discoverability --- CHANGELOG.md | 7 ++++ CITATION.cff | 18 +++++++++ README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++------- 3 files changed, 113 insertions(+), 13 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CITATION.cff diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..814dc10 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +Release notes and version history for freshmint are tracked via GitHub Releases: + +- https://github.com/onflow/freshmint/releases + +For user-facing changes per version, see the Releases page. diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..115d45a --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,18 @@ +cff-version: 1.2.0 +message: "If you use freshmint in your research or reference it, please cite it as below." +title: "freshmint: TypeScript NFT minting toolkit for the Flow network" +authors: + - name: "Flow Foundation" + website: "https://flow.com" +repository-code: "https://github.com/onflow/freshmint" +url: "https://flow.com" +license: Apache-2.0 +type: software +keywords: + - flow + - flow-network + - cadence + - nft + - nft-minting + - typescript + - ipfs diff --git a/README.md b/README.md index 01134c7..9f042cd 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,98 @@ -# Freshmint ๐Ÿƒ +# freshmint โ€” TypeScript NFT Minting Toolkit for Flow -Freshmint is a tool for building NFT-based applications on Flow. +[![License](https://img.shields.io/github/license/onflow/freshmint)](./LICENSE) +[![Latest Release](https://img.shields.io/github/v/release/onflow/freshmint?include_prereleases)](https://github.com/onflow/freshmint/releases) +[![Discord](https://img.shields.io/badge/Discord-Flow-5865F2?logo=discord&logoColor=white)](https://discord.gg/flow) +[![Built on Flow](https://img.shields.io/badge/Built%20on-Flow-00EF8B)](https://flow.com) +[![npm](https://img.shields.io/npm/v/freshmint)](https://www.npmjs.com/package/freshmint) -> :warning: This project is still in development. -> -> The current alpha version is not yet intended for production (i.e. mainnet) use. Please expect breaking changes as the tool evolves! +Freshmint is a TypeScript toolkit for minting NFTs on the Flow network. It bundles batch minting workflows, metadata management, IPFS pinning integration, and ready-to-deploy Cadence contracts so builders can ship NFT projects on Flow without reinventing the pipeline. -## Getting started +## TL;DR -Follow the [getting started guide](./docs/getting-started.md) to create your first Freshmint project! +- **What:** A TypeScript toolkit and CLI for creating, minting, and managing NFT collections on Flow. +- **Who it's for:** NFT project teams, Cadence developers, and JavaScript/TypeScript builders shipping NFT drops on Flow. +- **Why use it:** Combines Cadence NFT contracts, metadata handling, and IPFS workflows into one TypeScript package so you can go from assets to on-chain mint with less glue code. +- **Status:** See [Releases](https://github.com/onflow/freshmint/releases) for the latest version. This project was published as an alpha โ€” review the releases page before production use. +- **License:** Apache-2.0 +- **Related repos:** [onflow/flow-nft](https://github.com/onflow/flow-nft) ยท [onflow/nft-catalog](https://github.com/onflow/nft-catalog) ยท [onflow/flow-cli](https://github.com/onflow/flow-cli). Open-sourced since 2021. -## Development +## Quick Start -This repository contains both TypeScript and Cadence source code. +Follow the [getting started guide](./docs/getting-started.md) to scaffold your first Freshmint project. A typical flow: -### Cadence +1. Install the CLI from the [`freshmint` package](./packages/freshmint). +2. Initialize a new project directory with a Cadence contract, metadata schema, and asset folder. +3. Configure your Flow account, network (emulator, testnet, or mainnet), and IPFS/pinning provider. +4. Mint NFTs in batches from a CSV or JSON metadata source. -The Cadence contracts, transactions and scripts are maintained in the [cadence](./cadence) directory. +See the per-package READMEs under [`packages/`](./packages) for installation and API details. -### TypeScript +## Features -Freshmint is made up of several TypeScript packages located in the [packages](./packages) directory. +- **Batch minting**: Mint NFTs in batches driven by CSV or JSON metadata inputs. +- **Metadata management**: Define and validate NFT metadata schemas compatible with Flow NFT metadata views. +- **IPFS pinning**: Pin NFT media and metadata to IPFS through supported pinning providers. +- **Cadence contracts**: Ready-to-deploy Cadence contracts for NFT collections, maintained in the [`cadence`](./cadence) directory. +- **Monorepo packages**: Core library, CLI, React integrations, and a Cadence loader live in [`packages/`](./packages). +- **TypeScript first**: Full TypeScript types for metadata, mint flows, and contract interactions. + +## Example + +Freshmint is organized as a monorepo. The primary entry points are: + +- [`packages/freshmint`](./packages/freshmint) โ€” the `freshmint` CLI for project scaffolding and minting. +- [`packages/core`](./packages/core) โ€” the core TypeScript library used by the CLI and integrations. +- [`packages/react`](./packages/react) โ€” React helpers for Freshmint-powered frontends. +- [`packages/cadence-loader`](./packages/cadence-loader) โ€” utilities for loading Cadence source files. + +Refer to [`docs/getting-started.md`](./docs/getting-started.md) for end-to-end examples, and [`docs/metadata.md`](./docs/metadata.md) for the metadata schema format. + +## How It Works + +Freshmint combines three layers: + +1. **Cadence contracts** (in [`cadence/`](./cadence)) implement the on-chain NFT collection, following the [NonFungibleToken](https://github.com/onflow/flow-nft) standard and metadata views. +2. **TypeScript packages** (in [`packages/`](./packages)) wrap contract deployment, transaction building, metadata validation, and IPFS pinning into a single JavaScript/TypeScript API and CLI. +3. **Developer workflow**: you provide metadata (CSV/JSON) and assets; Freshmint pins media to IPFS, writes metadata into Cadence transactions, and submits batched mint transactions to the configured Flow network. + +The result is a repeatable pipeline from a local asset folder to an on-chain NFT collection on Flow. + +## FAQ + +**What is Freshmint?** +A TypeScript toolkit and CLI for creating and minting NFT collections on the Flow network, including Cadence contracts, metadata tooling, and IPFS workflows. + +**What networks does it target?** +Freshmint targets Flow โ€” the emulator, testnet, and mainnet. See [`docs/testnet.md`](./docs/testnet.md) for testnet-specific guidance. + +**Which smart contract language does Freshmint use?** +Freshmint's on-chain components are written in [Cadence](https://cadence-lang.org), the resource-oriented smart contract language for Flow. The Cadence sources live in [`cadence/`](./cadence). + +**Do I need Node.js to use Freshmint?** +Yes. Freshmint is published as TypeScript packages and a Node.js CLI. See [`docs/nodejs.md`](./docs/nodejs.md) for Node.js usage. + +**How does Freshmint handle NFT metadata?** +Metadata schemas are defined per project and validated before minting. Freshmint can pin metadata and media to IPFS and record the resulting CIDs in Cadence mint transactions. See [`docs/metadata.md`](./docs/metadata.md). + +**Is Freshmint production-ready?** +Check the [Releases](https://github.com/onflow/freshmint/releases) page for current version and release notes before using it in production. + +**Where do I report bugs or request features?** +Open an issue in this repo, or join the community channels listed below. + +## Community & Support + +- [Flow Discord](https://discord.gg/flow) โ€” real-time developer chat. +- [Flow Forum](https://forum.flow.com) โ€” longer-form discussions and announcements. +- [Flow Improvement Proposals (FLIPs)](https://github.com/onflow/flips) โ€” protocol and ecosystem governance. +- [GitHub Issues](https://github.com/onflow/freshmint/issues) โ€” bug reports and feature requests for Freshmint. + +## About Flow + +This repo is part of the [Flow network](https://flow.com), a Layer 1 blockchain built for consumer applications, AI Agents, and DeFi at scale. + +- Developer docs: https://developers.flow.com +- Cadence language: https://cadence-lang.org +- Community: [Flow Discord](https://discord.gg/flow) ยท [Flow Forum](https://forum.flow.com) +- Governance: [Flow Improvement Proposals](https://github.com/onflow/flips)