JavaScript, Node.js apps and Exponential #

A JavaScript site is a front end; its content lives somewhere else: in Markdown or MDX files in the repository, in a headless CMS, in a database behind an API, or inside the code. So "migrating a Next.js site" means two decisions: where the content goes (into Exponential), and what renders the site (Exponential's templates, or the existing front end reading Exponential).

Migration hub · Checklist · Mapping · Tools

Contents #

• 1. Where the content of a JavaScript site lives
• 2. Content into Exponential
• 3. Keeping the JavaScript front end: Exponential as its content source
• 4. Addresses and redirects
• 5. From Exponential to a JavaScript front end
• 6. Checklist

1. Where the content of a JavaScript site lives #

Next.js stores no content of its own. According to its documentation, output: 'export' makes next build write static HTML, CSS and JavaScript to out/ (next export was removed in version 14). That output is a complete crawl target for the static HTML method when the sources are hard to read.

2. Content into Exponential #

1. Collect the sources: list the content directories, data files and APIs the app reads at build or request time (look at getStaticProps/generateStaticParams, loaders, or the data layer of your framework).
2. Convert Markdown/MDX: in Node.js, parse the front matter and render Markdown to HTML with the library the site already uses, so the result matches what visitors saw. MDX components (<Callout>, <Video>) have no HTML equivalent: map each to an Exponential custom tag or embed, or render it to plain HTML.
3. Write JSON rows: remote id from the file path or slug (md-blog/2024/hello), title, date, tags, author, the HTML, the route.
4. Import with the script skeleton on the server, or xrowextract's importer with --map. Media from public/ become image/file objects.
5. Templates: build TPL templates, or keep the front end (3).

3. Keeping the JavaScript front end: Exponential as its content source #

Exponential can be the headless content source of an existing front end; editors work in the Exponential admin, the front end fetches content at build or request time.

Writes over REST are limited (create and delete at v2; update answers 501 for now), so bulk imports are done on the server, not from the front end.

4. Addresses and redirects #

• Keep the routes: give each node the alias of its old route, so the front end (or Exponential's own templates) can serve the same paths.
• According to the Next.js documentation, a static export does not support redirects, rewrites or headers from next.config.js, nor Route Handlers that use the request, ISR, Server Actions or default image optimization: redirects of a statically exported site belong to the host or web server.
• When Exponential renders the site, the redirects are URL aliases and wildcards (checklist, 4).

5. From Exponential to a JavaScript front end #

• Keep Exponential as the content source and build the new front end against its REST API (3).
• Or move the content out: export with xrowextract to JSON (leaving Exponential), render XmlText to HTML or Markdown, and write the files or the headless CMS of your choice.
• Image aliases (scaled renditions) are produced by Exponential; a static site needs its own image pipeline.

6. Checklist #

• To do: Every content source of the app listed (files, data, APIs, hard-coded).
• To do: Markdown rendered with the site's own renderer; MDX components mapped.
• To do: Imported with remote ids from paths or slugs; media imported.
• To do: Decision made: Exponential templates, or the front end reading Exponential (API key scopes set).
• To do: Routes preserved or redirected on the host.

Sources #

• Next.js static exports: https://nextjs.org/docs/app/guides/static-exports

This page is part of the Exponential documentation and is free documentation under the GNU Free Documentation License 1.3 or any later version (the license of this documentation).