Simplify usage of Lens API with @use-lens and graphql-codegen

🔗 Links

• andriishupta | Github
• Use Lens | Github
• Lens API
• GraphQL Code Generator

📰 Published on

• Hashnode 💻
• Medium ✍️
• DEV Community 👩‍💻👨‍💻

🤓 Intro

Recently, I have used Lens API to build some playground apps and noticed a repetitive task: I created Lens API Queries and Mutations for every project and used GraphQL Code Generator to use React hooks with Apollo Client.

After 2nd time doing the same job, I decided to create a library for easier use of Lens API that would save me some time to do actual work.

I have never created open-source packages and thought it would be a great experience to do it, even if only I would use it 😅.

npm @use-lens so far contains 2 packages - CLI and react-apollo. Later in this article, I will explain how to use them and when, and the same information could be found in the repo's README.md.
I will explain how I see the best use of @use-lens/* later in the article.

Also, I liked Lens Protocol so much that I have created Github Organization Use Lens, where I plan to develop and publish some tools, examples and apps working on top of Lens.

Technology

Lens Protocol is a composable and decentralized social graph, ready for you to build on so you can focus on creating a great experience, not scaling your users.

Own your content. Own your social graph. Own your data.

If you have read so far - you know what Lens API is and how to use it. If you are here to check out @use-lens or just to check how to generate GraphQL code - educate yourself of Lens Protocol and API here:

🌿 https://docs.lens.xyz.

GraphQL Code Generator - is a tool to build read-to-use code from your GraphQL schema and operations with a simple CLI with a lot of plugins for different frameworks: React, Next.js, Svelte, Vue with Apollo, URLQ and others - you name it.

🧑‍💻 How to

Generate with @use-lens/cli

npm install --save-dev @use-lens/cli
use-lens generate %PACKAGE%

with npx

npx @use-lens/cli generate %PACKAGE%

This would copy essential files of Lens API to your repo and would run graphql-codegen to generate the code. By default, it would go to src/lens-api/index.ts.
From here, you could adjust tsconfig.json to use it with @use-lens shortening, so it would feel like a package usage. More on how to do it here.

With @use-lens/*

The simple npm install --save @use-lens/%PACKAGE% and use it as a regular package.

import {
  GlobalProtocolStatsDocument,
  GlobalProtocolStats as GlobalProtocolStatsType,
  useGlobalProtocolStatsQuery,
  useGlobalProtocolStatsLazyQuery,
} from '@use-lens/react-apollo'

Manual GraphQL Code Generator

The default approach is simple and could be followed by official docs here

On high-level:

• install @graphql-codegen/cli
• pick a plugin for your stack: for example, react-apollo and install it
• get your GraphQL Schema and Documents
• create basic codegen.yml for graphql-codegen
• run graphql-codegen

In your codegen.yml, you should specify schema, documents, where to save, and with what:

schema: schema.graphql # full schema; could be HTTP link
documents: documents.graphql # queries and mutations that you want to have
generates:
  ./src/my-api/index.ts: # where to save
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo # stack that you are going to use

⚠️ CAUTION

🌿 https://docs.lens.xyz/docs/introduction:

This API is beta and not production complete yet, which means that we could change schemas and endpoints at any time without warning or notice to you. When this API is production ready, we will remove this beta warning and will endeavor to ensure that there are no changes going forward unless a major change to the protocol itself is required.

Lens API is not production complete, and so is @use-lens/*. Please, keep this in mind when going to production.

Recommended use

If you want to play with Lens API - don't hesitate and install some of the @use-lens/* packages - it will give you all you need to start.

If you want to have more control - use @use-lens/cli to generate code locally. This would copy essential files that a package contains and would run graphql-codegen.

You would be able to do more with codegen.yml.

👨‍🏫 React with Apollo Client

For @use-lens/react-apollo, I have prepared an example of how to use it.

Check out the source code here

🤝 Lens API Documents

The complete set of Lens API Documents has been taken from api-examples, a repo of Lens Protocol that shows how to use Lens API.
The same (or similar) queries are given as examples in Lens API docs.

📚 Summary

If you would like to use Lens API to see what it is - simplify your developer experience by using @use-lens or GraphQL Code Generator.

Thanks for reading! 🙇