npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

next-spa

v0.3.9

Published

SPA functionality with dynamic file-system routing for NextJS

Downloads

35

Readme

next-spa

SPA functionality with dynamic file-system routing for NextJS

Aim

This project was created with one simple goal in mind:

"To add dynamic route handling to static sites built with NextJS"

Features

  1. Dynamic file-system routing. You can even make use of this if you're developing an SSR app!

  2. Client-side SPA route handling of dynamic routes.

  3. Generate hosting config for serve.js and Now.sh

How to use

Installation:

  1. npm i --save next-spa or yarn add next-spa

  2. Add next-spa dev script to package.json: "spa:dev": "next-spa dev"

Add 'withSPA' to 'next.config.js':

const withSPA = require('next-spa').withSPA

module.exports = withSPA({
  ...your-config...
})

SPA fallback - 404.html:

By default next-spa is configured to export a 404.html file as the default SPA fallback. This fallback file handles the client redirecting for your dynamic routes.

You can change the name of the fallback file in your next.config.js file:

const withSPA = require('next-spa').withSPA

module.exports = withSPA({
  ...your-config...,
  nextSPA: {
    fallback: 'spa-fallback.html'
  }
})

Add 'withSPARouter' to 'pages/_app.js':

Create custom _app.js file and connect the SPA Router. This file will also be required if you wish to use a custom PageLoader (see next step).

import App, { Container } from 'next/app'
import { withSPRouter } from 'next-spa/router'

class _App extends App {
  render () {
    const { Component, pageProps } = this.props

    return (
      <Container>
        <Component {...pageProps} />
      </Container>
    )
  }
}

export default withSPARouter(_App)

Custom 'PageLoader':

next-spa comes with a default PageLoader that is displayed on dynamic routes while the client is loading.

You can override the default PageLoader in _app.js:

import App, { Container } from 'next/app'
import { withSPRouter } from 'next-spa/router'

import MyCustomLoader from '../components/MyCustomLoader'

class _App extends App {
  static async getInitialProps({ Component, ctx }) {
    ...
  }
  render() {
    const { Component, pageProps } = this.props
    return (
      <Container>
        <Component {...pageProps} PageLoader={MyCustomLoader} />
      </Container>
    )
  }
}

export default withSPARouter(_App)

Add your first dynamic route:

Dynamic file-system routes require their names to be prefixed with an underscore (_) eg:

- pages
  |
  - index.js
  |
  - products
    |
    - _id.js

The file name that you use will be the key that gets passed to the query object at runtime.

Note: For static sites, the slug value (or id in the above example) won't be available in the query object until the component has mounted on the client.

Replace next/link & next/router

Under the hood next-spa uses next-routes for its dynamic routing; also exposing the Link and Router apis.

Be sure to replace any next/link or next/router import with next-spa/link or next-spa/router equivalent.

Refer to the next-routes documentation for guidence on Link and Router.

Run the dev environment:

To run a dev environment you have to replace your the next dev command with next-spa dev.

Note: If you are using next-spa in a SSR app you will also need to replace the next start command with next-spa start.

Note: If you are using a custom server then you will also need to add next-spa configutation your server file:

const express = require('express')
const nextSPA = require('next-spa').default  // Replace require('next').

const dev = process.env.NODE_ENV !== 'production'
const port = parseInt(process.env.PORT, 10) || 3000
const app = nextSPA({ dev })  // And use nextSPA instead to create the app.
const handler = app.getRequestHandler()

app.prepare()
  .then(() => {
    const server = express()

    server.get('*', (req, res) => {
      return handler(req, res)
    })

    server.listen(port, (err) => {
      if (err) throw err
      console.log(`> Ready on http://localhost:${port}`)
    })
  })

Build and Export your app:

You can still use the same NextJS commands to build (next build) and export (next export) your app.

Serve you app:

We recommend using serve.js to serve your static site locally.

Install: npm i -g serve

Add Script: "serve": "cd <path-to-export> && serve"

Hosting rewrites:

Generally you will need to configure rewrites with you hosting provider, but if you are using serve.js to serve your site locally then you can use next-spa to genterate a serve.json rewrites file.

By default all dynamic routes are rewritten to point to the SPA fallback file.

Command: next-spa create-serve-config

Command options:

  • -o <outdir> Should be the path to your exported site

Note: The same config file can also be used if you are deploying serverlessly through Now.sh

Export dynamic page:

You can also optionally export static versions of your dynamic pages as well.

These exported pages will contain the same spa functionality as your fallback file allowing you to use rewrites to point your dynamic routes to these files instead.

You can enable dynamic page exports through your next.config.js file.

const withSPA = require('next-spa').withSPA

module.exports = withSPA({
  ...yourNextConfig,
  nextSPA: {
    fallback: 'spa-fallback.html',
    exportDynamicPages: true,
  }
})

Note: If using the next-spa create-serve-config to create serve.js rewrites, next-spa will automatically configure your dynamic routes to point to their associated page.