This week's portion

This page has not been reviewed by a human.

You want a page that shows this week's Torah portion. You don't want to edit the reference by hand each week.

When the example loads, it looks up the portion for your current local date. Reload the page to update it. It makes one client call to Sefaria's calendar, reads the portion's reference from the answer, and sets that reference on a Source Card.

This is a complete app (Vite and TypeScript) in examples/weekly-portion. It loads live when this page opens. You can't edit it here. To read its source, see the example on GitHub.

Open in a new tab

How it works

The card starts empty

The page holds an empty Source Card. With no sref, the card stays blank (its status is empty) and makes no request.

<sefaria-source-card></sefaria-source-card>

To register the elements, main.ts imports the package root. Your own app does the same:

import "@sefaria/web-components";

The calendar call

The app calls calendars.getCalendars from @sefaria/api-client. That call goes to Sefaria's /api/calendars. You pass year, month and day together, or Sefaria uses today. You pass diaspora to pick the reading: "1" for the diaspora and "0" for Israel. The client checks the response against its schema.

examples/weekly-portion/src/app.ts

/** Asks Sefaria's calendar for the week's Torah portion and shows it on a Source Card. */
export async function showWeeklyPortion({
  card,
  status,
  date = new Date(),
  diaspora = true,
  client = createSefariaClient(),
}: WeeklyPortionOptions): Promise<string | undefined> {
  const result = await calendars.getCalendars({
    client,
    query: {
      year: date.getFullYear(),
      month: date.getMonth() + 1,
      day: date.getDate(),
      diaspora: diaspora ? "1" : "0",
    },
  });
  const portion = result.data?.calendar_items?.find(
    (item) => item.title?.en === PORTION_TITLE,
  );
  if (portion?.ref === undefined) {
    status.textContent =
      "Sefaria's calendar has no Torah portion for this date.";
    return undefined;
  }
  status.textContent = `This week's portion: ${portion.displayValue?.en ?? portion.ref}`;
  card.sref = portion.ref;
  return portion.ref;
}

The app then looks for the calendar item whose title.en is "Parashat Hashavua". It sets that item's ref as the card's sref. It also shows the portion's name (displayValue.en) in a status line.

If the calendar has no portion for that date, the status line says no portion was found and the card stays blank. If the call fails, the status line shows an error message instead.

Requests

The page makes one calendar request. The Source Card then makes its own text request, or two when a requested translation language is missing. The card loads the whole portion, which can be long.

What the test checks

The test uses a fixed date, 8 January 2027. It uses a real calendar response saved from Sefaria on 29 September 2026. It checks that there is exactly one calendar request, with year=2027, month=1, day=8 and diaspora=1. It also checks that the card receives Exodus 6:2-9:35, which is Vaera.

Change it

For the Israel reading, pass diaspora: false. The app sends "0".

The same response lists other learning schedules that have a ref, such as Haftarah, Daf Yomi and 929. Each is another entry in calendar_items, with its own title and ref. To show one, match its title.en instead and change the status wording to match. Some entries only link to a collection and have no ref, so they can't feed a Source Card. See Sefaria's calendar documentation for the response.

Run it locally

From the repository root, use Node.js 22.12 or later and the pnpm version pinned in package.json:

pnpm install
pnpm build
pnpm --filter @sefaria-example/weekly-portion dev

To install the packages in your own project, see Install and status.

Next steps

• Show an attributed passage covers the Source Card used here.
• Start here: data and text tools covers the client on its own.

For every client function, see the client reference. For the package paths you can import, see Package imports and exports.