Content Creation

The Publication Metadata Standard is a specification that outlines the structure of Lens Publication Metadata objects.

This is a self-describing specification, meaning the data itself includes all the information necessary for its validation.

You can construct Publication Metadata in two ways:

npm install zod @lens-protocol/metadata@latest

import { textOnly } from '@lens-protocol/metadata';
const metadata = textOnly({  content: `GM! GM!`,});

You can host Publication Metadata anywhere, as long as it's publicly accessible via a URI and served with the appropriate Content-Type: application/json header.

Commonly, integrators use solutions like IPFS or Arweave for hosting Publication Metadata.

In the upcoming examples, we'll assume you have a function named uploadJson. This function takes a JavaScript object, uploads it, and returns the public URI of the uploaded file.

import { textOnly } from "@lens-protocol/metadata";import { uploadJson } from "./my-upload-lib";
const metadata = textOnly({  content: `GM! GM!`,});
const metadataURI = await uploadJson(metadata);

Once you've uploaded the Publication Metadata, you can create a Lens Post.

import { textOnly } from '@lens-protocol/metadata';import { useCreatePost } from '@lens-protocol/react-web';
import { uploadJson } from "./my-upload-lib";
export function Composer() {  const { execute, loading, error } = useCreatePost();
  const submit = async (event: React.FormEvent<HTMLFormElement>) => {    event.preventDefault();    const formData = new FormData(event.currentTarget);
    // create post metadata    const metadata = textOnly({      content: formData.get('content') as string,    });
    // publish post    const result = await execute({      metadata: await uploadJson(metadata),    });
    // detect if an early error occurred    if (result.isFailure()) {      window.alert(result.error.message);      return;    }
    // optional: wait for the transaction to be mined and indexed    const completion = await result.value.waitForCompletion();
    // detect if a minining/indexing error occurred    if (completion.isFailure()) {      window.alert(completion.error.message);      return;    }
    // post was created    const post = completion.value;    window.alert(`Post ID: ${post.id}`);  };
  return (    <form onSubmit={submit}>      <textarea        name="content"        minLength={1}        required        rows={3}        placeholder="What's happening?"        disabled={loading}      ></textarea>
      <button type="submit" disabled={loading}>        Post      </button>
      {!loading && error && <p>{error.message}</p>}    </form>  );}

const { execute, loading, error } = useCreatePost();
// ...
const result = await execute({  metadata: await uploadJson(metadata),  sponsored: false,});

An uploader is an implementation of the Uploader class. It encapsulates your strategy for uploading Publication Metadata object and any media files referenced by it.

You can define two types of uploaders:

import { useMemo } from "react";import { Uploader, useIdentityToken } from "@lens-protocol/react-web";
export function useUploader() {  const idToken = useIdentityToken();
  return useMemo(() => {    return new Uploader(async (file: File) => {      const response = await fetch("/api/file", {        method: "POST",        body: file,        headers: {          Authorization: `Bearer ${idToken}`,        },      });
      if (!response.ok) {        throw new Error("Failed to upload");      }
      return response.headers.get("Location")!;    });  }, [idToken]);}

Creating the Publication Metadata object for the optimistic approach is similar to the non-optimistic one, with the exception that you can directly reference local files using their local URLs.

In the next step, the React SDK will handle the upload of any referenced media files using the uploader you defined. It will replace the local file URLs with the uploaded URIs and then upload the Publication Metadata JSON file.

Here we will show how to embed local URLs in the metadata object for both React Web and React Native environments.

import { image, MediaImageMimeType } from "@lens-protocol/metadata";import { fileToUri } from "@lens-protocol/react-web";
// ...
const submit = async (event: React.FormEvent<HTMLFormElement>) => {  event.preventDefault();  const form = event.currentTarget;  const formData = new FormData(form);
  const file = formData.get('image') as File;
  // create post metadata  const metadata = image({    image: {      item: fileToUri(file),      type: MediaImageMimeType.JPEG,      altTag: "My image",    },  });
  // ...};
return (  <form onSubmit={submit}>    <input type="file" name="image" accept={MediaImageMimeType.JPEG} required />    <button type="submit">Post</button>  </form>);

Next, use the useOptimisticCreatePost hook to optimistically create a Lens Post.

import { useOptimisticCreatePost } from "@lens-protocol/react-web";import { textOnly } from "@lens-protocol/metadata";
import { useUploader } from "./useUploader";
// ...
const uploader = useUploader();const { data, execute, loading, error } = useOptimisticCreatePost(uploader);
const post = (content: string) => {  const metadata = textOnly({ content });
  // invoke the `execute` function to create the post  const result = await execute({    metadata,  });
  // check for failure scenarios  if (result.isFailure()) {    window.alert(result.error.message);  }};

Immediately after the execute call, the data property updates with the optimistic Post object.

The hook enables optimistic behavior only when the Signless Experience is possible. If not, the hook will not return optimistic data.

This limitation is due to the experimental nature of the hook. As its usage expands, the optimistic behavior will accommodate more scenarios.

Optionally, you can wait for the full completion of the post creation.

const post = (content: string) => {  const metadata = textOnly({ content });
  // invoke the `execute` function to create the post  const result = await execute({    metadata,  });
  // check for failure scenarios  if (result.isFailure()) {    window.alert(result.error.message);  }
  // wait for full completion  const completion = await result.value.waitForCompletion();
  // check for late failures  if (completion.isFailure()) {    window.alert(completion.error.message);    return;  }
  window.alert(completion.value);};

Eventually, the data property will automatically update, making the final Post object available for further interactions. At this stage, you can enable all operations on the Post.

Define an App ID that uniquely identifies your application (e.g., Hey, Orb) and include it in the Publication Metadata as shown below.

import { textOnly } from '@lens-protocol/metadata';
const metadata = textOnly({  appId: "<my-app-id>",  content: `Hello world!`,});

Generate an EVM key pair and communicate the corresponding address to the Lens Protocol team via the Lens Developer Garden Telegram group alongside with your App ID.

Use the signMetadata helper function to sign the Publication Metadata object with the private key.

import { privateKeyToAccount } from "viem/accounts";import { signMetadata } from "@lens-protocol/metadata";
const account = privateKeyToAccount(process.env.APP_PRIVATE_KEY);
const signed = await signMetadata(metadata, (message) =>  account.signMessage({ message }));

This process results in a signed copy of the original Publication Metadata object. Use this signed object to create your publication, as previously explained on this page.

Next, when requesting publications, include your App ID in the list of apps to fetch publication metadata for alongside any other App IDs you want to include.

Omit this filter to fetch publications for all apps, including yours.

import { appId, PublicationType, usePublications } from '@lens-protocol/react-web';
// ...
const { data, loading, error } = usePublications({  where: {    publicationTypes: [PublicationType.Post]    metadata: {      publishedOn: [appId('<my-app-id>')],    },  },});