agentleFS
Sign inStart free
datopiandatopian/portaljs/skills/portaljs-connect-ckan/SKILL.md

portaljs-connect-ckan

Skill2.4k starsChanged 12 days agoMITView on GitHub

Wire a scaffolded PortalJS portal to a CKAN backend over its API. Generates a tiny server-side fetch client (no runtime dependency) and feeds the /search catalog and /@namespace/slug showcases from CKAN instead of datasets.json. Use when connecting an existing portal to a live CKAN instance instead of a static manifest.

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Verify the CKAN backend is reachable via package_search?rows=1, and validate each org filter via organization_show.

    line 51
  2. Very specific:

    Verify the build with npx next build.

    line 61

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PortalJS — Connect CKAN

Overview

Connect an existing portaljs-catalog portal to a live CKAN backend for the "decoupled / any backend" path. The portal stops reading the static datasets.json manifest (and files in /public/data/) and instead feeds its two data surfaces — the /search catalog and the /@namespace/slug showcases — straight from a CKAN instance's REST API (package_search / package_show) through a generated fetch client. Output is plain, editable Next.js code with no runtime dependency — never @portaljs/ckan, whose bundle wires React UI components to React 18 internals and crashes at import under the template's React 19. Pages fetch CKAN server-side in getStaticProps/getStaticPaths, so the catalog is pre-rendered at build time and the site can still be statically deployed. Run this right after portaljs-new-portal to swap a freshly scaffolded portal's sample data over to CKAN.

Prerequisites

  • A scaffolded PortalJS portal (see portaljs-new-portal) with package.json, pages/, datasets.json, pages/search.tsx, and pages/[owner]/[slug].tsx present.
  • A CKAN base URL that is publicly reachable, e.g. https://demo.dev.datopian.com.
  • Node 18+ and npm available in the portal directory (no new packages are installed).

Instructions

The canonical, full step-by-step workflow is .claude/commands/portaljs-connect-ckan.md — the single source of truth. Read and follow it when executing. Summary:

  1. Gather input from $ARGUMENTS — CKAN base URL (required), org filter (optional), group filter (optional), portal directory (default .). If the URL is missing, interview the user; never dead-end with a missing-input error.
  2. Validate the target directory is a portaljs-catalog portal; if not, suggest portaljs-new-portal instead of failing silently.
  3. Verify the CKAN backend is reachable via package_search?rows=1, and validate each org filter via organization_show; on failure, explain and re-prompt rather than dead-ending.
  4. Generate lib/ckan.ts — a self-contained server-side fetch client wrapping package_search and package_show, with DMS, ORG_FILTER, GROUP_FILTER, and MAX_DATASETS as editable constants.
  5. Rewire pages/search.tsx to list datasets from package_search, linking each to /@namespace/slug via datasetHref; leave pages/index.tsx untouched.
  6. Overwrite pages/[owner]/[slug].tsx to pre-render one page per dataset via getStaticPaths and fetch details with package_show, previewing tabular resources through the existing Table component.
  7. Verify the build with npx next build; fix any error before reporting success.
  8. Report what changed: client, catalog, showcase, filters, and static page count.

Output

  • Created: lib/ckan.ts (fetch wrapper client — no dependency added to package.json).
  • Modified: pages/search.tsx (catalog reads package_search); pages/[owner]/[slug].tsx (showcase reads package_show, overwritten to drop the datasets.json source).
  • Unchanged: pages/index.tsx (still the static search-first landing page).
  • UI strings: any text it adds to JSX renders through t() (lib/i18n.ts), with the keys added to locales/en.json and every other locales/*.json; npm run i18n:check passes.
  • Verified: npx next build succeeds and prints the static page count.
  • Result: /search and /@namespace/slug are served from the CKAN backend; the DMS env var can override the base URL at deploy time without editing code.

Error Handling

SymptomCauseFix
Missing CKAN URLUser invoked the skill with no $ARGUMENTSAsk for the base URL (and optional org/group filter); never error out.
package_search request fails or times outURL isn't a reachable CKAN rootTell the user, ask them to confirm the URL, and retry.
Org filter not foundorganization_show returns success: falseList valid orgs from organization_list and ask which one was meant.
Catalog renders empty after connectingWrong org/group filter name in lib/ckan.tsClear or correct the filter constants and rebuild.
next build failsTypo in substituted CKAN_URL or bad TypeScript editPrint the log, fix the first error, and re-run before reporting success.
<Table> fails to load a resourceCKAN resource host blocks CORSNote that the Download link still works; prefer datastore-backed resources.

Examples

Example 1 — Public CKAN demo, no filters

/portaljs-connect-ckan url=https://demo.dev.datopian.com

Example 2 — Restrict the catalog to one organization

/portaljs-connect-ckan url=https://demo.dev.datopian.com org=my-org

Example 3 — Filter by group and target a specific portal directory

/portaljs-connect-ckan url=https://data.example.gov group=education dir=./my-portal

Resources

Download now (ZIP)

Trending

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Aug 30: 0 new projectsWeek of Sep 6: 0 new projectsWeek of Sep 13: 0 new projectsWeek of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projects
Aug 2026Sep 2026Oct 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Who's talking about datopian/portaljs

The biggest 5 of 38 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 38

Talked about on GitHub and Hacker News (38 times).

On GitHub · 37

32 more on GitHub

On Hacker News · 1

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free