@vocdoni/react-providers

This package includes react context & providers for integration with the Vocdoni protocol via the Vocdoni SDK.

The best place to learn about using this package is the developer portal.

Table of Contents

• Getting Started
• Reference
• Examples
• Preview
• Disclaimer
• Contributing
• License

Getting Started

Using your favorite package manager:

yarn add @vocdoni/react-providers

The very first step is to add the <ClientProvider /> as a wrapper of your application or, at least, of your election:

import { ClientProvider } from '@vocdoni/react-providers'

const App = () => {
  const signer = /* any ethers based signer */
  return (
    <ClientProvider env='stg' signer={signer}>
      {/* your actual app code */}
    </ClientProvider>
  )
}

ClientProvider is a dependency of the other providers, so you'll have to ensure you initialize it first as the parent.

i18n (i18next)

This package relies on i18next + react-i18next. Your app must initialize i18next and provide the I18nextProvider.

Example initialization:

import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import { reactProvidersResources, reactProvidersNamespace } from '@vocdoni/react-providers'

i18n.use(initReactI18next).init({
  lng: 'en',
  resources: reactProvidersResources, // merge with your app resources
  ns: [reactProvidersNamespace],
  defaultNS: reactProvidersNamespace,
})

Extraction guidance

We export base resources so you can merge them with your app translations:

import { reactProvidersResources } from '@vocdoni/react-providers'

If you want to scan for keys in workspace/local dev (monorepo), point your extractor to the source:

// i18next-parser.config.cjs
module.exports = {
  locales: ['en'],
  defaultNamespace: 'react-providers',
  namespaceSeparator: ':',
  keySeparator: '.',
  input: ['../packages/react-providers/src/**/*.{ts,tsx}', 'src/**/*.{ts,tsx}'],
  output: 'src/locales/$LOCALE/$NAMESPACE.json',
}

For published installs, the package ships dist only. Do not scan node_modules. Scan your app code and merge with reactProvidersResources instead.

How to create your translation JSON files

If you want to add a new language, use the exported base resources as the key template and fill in translations on the app side.

Example: create src/locales/es/react-providers.json

import { reactProvidersResources, reactProvidersNamespace } from '@vocdoni/react-providers'

const base = reactProvidersResources.en[reactProvidersNamespace]

// Then translate values into your JSON file using the same keys:
// src/locales/es/react-providers.json
// {
//   "errors": {
//     "unauthorized": "No autorizado para votar"
//   }
// }

Load it with i18next:

import esReactProviders from './locales/es/react-providers.json'

i18n.addResourceBundle('es', reactProvidersNamespace, esReactProviders, true, true)

Reference

The developer portal includes a reference for using the @vocdoni/react-providers package.

Examples

You can find mock-functional usage of the react providers in the ui-components documentation. There is also real-world usage of many of the providers from this package in the code for the Vocdoni application front-end.

Preview

In addition to the live examples in the documentation, you can see this code in use at https://app.vocdoni.io/

Disclaimer

This project is a WIP and is subject to continuous changes during its development. We encourage you to review this repository and the developer portal for any changes.

Contributing

While we welcome contributions from the community, we do not track all of our issues on Github and we may not have the resources to onboard developers and review complex pull requests. That being said, there are multiple ways you can get involved with the project.

Please review our development guidelines.

License

This repository is licensed under the GNU Affero General Public License v3.0.

Vocdoni UI React Components
Copyright (C) 2024 Vocdoni Association

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.