OpenWikidubinc/dub

Import Links

Purpose and Scope

Link import is the migration path for bringing an existing portfolio of short links into Dub without recreating every link manually. The first-party help documentation describes a CSV import feature intended for large lists of links and migrations from providers that do not have a one-click importer. In practical terms, an import turns rows from a spreadsheet into normal Dub links, so the important reader task is not only preparing the file correctly, but also knowing how to verify the imported links once they land in the workspace.

The repository evidence for this page centers on the dashboard analytics area where those imported links become observable after import. The analytics route renders the same workspace analytics experience used for all links, and the link badge component displays per-link click, lead, and sale signals. That means import success should be understood as a handoff: CSV upload creates links, then link lists and analytics components provide confirmation, filtering, and performance review. Sources: apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/page.tsx, apps/web/ui/links/link-analytics-badge.tsx

Relevant Source Files

  • apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/client.tsx - Client wrapper for workspace analytics that handles loading state and event-limit gating before analytics children render.
  • apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/page.tsx - Dashboard route for the workspace Analytics page used to review imported links after they exist in Dub.
  • apps/web/ui/analytics/top-links.tsx - Analytics card that groups performance by links, folders, tags, base URLs, and full URLs, with query-string filters for drilling into imported data.
  • apps/web/ui/links/link-analytics-badge.tsx - Link-list badge that summarizes clicks, leads, sales, last-click state, and links directly into the analytics page for a specific link.
  • apps/web/lib/analytics/types.ts - Shared TypeScript types for analytics filters, group-by options, event types, response options, and event filters.
  • apps/web/lib/analytics/utils/index.ts - Barrel export for analytics helpers such as CSV conversion, query-string editing, export formatting, interval data, and plan-aware date-range validation.

CSV Import Workflow

A CSV import starts with file preparation. The official help article specifies that the CSV must contain a destination URL and a short link, while title, description, tags, and creation date are optional. Column names can vary, but the required meanings must be present so Dub can map each row to a link destination and a short URL. For migration projects, this distinction is important: the CSV is not just a list of destinations, because preserving the short-link value is what keeps external campaigns, bookmarks, and historical sharing patterns intact.

After the file is prepared, the user uploads it into a Dub workspace. The official guidance recommends creating the workspace first and, during migrations, generally delaying final custom-domain configuration until the links have been migrated. That sequencing reduces the risk of moving production traffic before the imported link set is ready. A good operational pattern is to import into the intended workspace, inspect the created links, resolve row-level errors or conflicts, and only then complete domain cutover or broader campaign updates.

Success and error feedback should be read at two levels. During import, user-facing messages indicate whether rows were accepted or need correction; after import, the dashboard provides durable confirmation that the resulting links exist and can be analyzed. Imported links are not a separate analytics object in the source evidence. They become part of the same link, folder, tag, URL, click, lead, and sale reporting surfaces as manually created links, so validation should move from upload feedback to ordinary workspace analytics once the import completes.

Post-Import Verification in Analytics

The workspace analytics page is the primary review surface after importing links. The page component renders a PageContent titled Analytics, wraps it in React Suspense, and mounts the shared Analytics UI through AnalyticsClient. That client first checks workspace state with useWorkspace; while loading it renders LayoutLoader, and if the workspace has exceeded events it renders WorkspaceExceededEvents except for the specific Pro-plan events-page exception. For an importer, this explains why analytics may show a loader or limit notice before any imported-link data is visible. Sources: apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/page.tsx, apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/client.tsx

The TopLinks component gives teams a structured way to verify that imported links are participating in reporting. It defines a links tab with subtabs for links, folders, and tags, and a urls tab with subtabs for base_urls and full_urls. Each subtab maps to a concrete analytics group-by value such as top_links, top_folders, top_link_tags, top_base_urls, or top_urls. This is useful after CSV import because the optional CSV tags and the imported short-link destinations can be inspected from multiple angles rather than only as a flat link list. Sources: apps/web/ui/analytics/top-links.tsx, apps/web/lib/analytics/types.ts

Filtering is also part of verification. TopLinks converts the active subtab into a query parameter key: linkId for individual links, url for base URLs, folderId for folders, and tagId for tags. Selected values are joined into the query string, and clearing a filter removes the corresponding parameter. A practical post-import workflow is to open Analytics, switch between link and URL groupings, apply filters for a suspicious imported item or tag, and compare click, lead, or sale totals against the expected campaign scope. Sources: apps/web/ui/analytics/top-links.tsx, apps/web/lib/analytics/utils/index.ts

Imported links also surface immediate status cues in link lists. LinkAnalyticsBadge reads link fields such as domain, key, trackConversion, clicks, leads, and saleAmount. It always includes click statistics, and it adds lead and sales indicators when conversion tracking is enabled or when the link already has lead or sale values. That conditional display matters for imports because older short links may initially show only click-oriented signals, while links connected to Dub conversion tracking can later expose deeper funnel activity.

The badge also handles the empty state. If a link has never been clicked, the tooltip says No clicks yet; otherwise it displays a last-click timestamp using timeAgo. On mobile, the badge links directly to /${slug}/links/analytics?linkId=${link.id}, which lands on the analytics page filtered to that link. On desktop, the tooltip can also expose share-dashboard actions when sharing is enabled. These behaviors make the imported-link review loop short: find the link, read its compact stats, and jump into filtered analytics when more detail is needed. Sources: apps/web/ui/links/link-analytics-badge.tsx, apps/web/app/app.dub.co/(dashboard)/[slug]/links/analytics/page.tsx

Analytics Types and Export Utilities

The analytics types module defines the vocabulary that post-import reporting uses. AnalyticsGroupByOptions is derived from the valid analytics endpoints list, AnalyticsResponseOptions includes clicks, leads, sales, and saleAmount, and filter types allow workspace, dates, partner, link, and event-oriented fields. EventsFilters keeps structural fields such as event, page, limit, and sort order required while allowing additional optional filters. These types keep imported-link review aligned with the same analytics contract used elsewhere in the app. Sources: apps/web/lib/analytics/types.ts

The analytics utilities barrel exports helpers for CSV conversion, query-string editing, analytics export formatting, interval data, and plan-aware date validation. Even though the supplied import implementation is outside this source set, these exports show that analytics data can be transformed and exported after links are present in the workspace. For migration audits, that is often the second half of the job: import the CSV, inspect dashboard success or error feedback, then export or filter analytics to prove that the resulting links are reachable and measurable. Sources: apps/web/lib/analytics/utils/index.ts

Practical Checklist

Use this checklist when importing links. First, prepare a CSV with destination URL and short link values, and include title, description, tags, and creation date where they improve organization or preserve context. Second, upload the file into the target workspace before routing production traffic through a newly configured domain. Third, address any import errors from the upload experience, especially missing required columns, malformed URLs, duplicate short links, or tag formatting problems. Finally, use the Analytics page, Top Links groupings, and link-level badges to confirm that the imported links appear under the expected links, tags, folders, and URL groupings.

Next, read the related link-management and analytics pages together. Importing is a migration workflow, but imported links become ordinary Dub links after creation. The most useful follow-up is to learn how create, update, delete, folders, tags, and analytics filters work, because those are the tools you will use to clean up migrated data, validate campaign performance, and decide when the imported workspace is ready for domain cutover.

Ask a question...