Deploy quasar to netlify with ssr mode

[dongwa]

Hello everyone,

I dedicated a lot of time and effort to successfully deploy Quasar on Netlify with SSR mode and I'd like to share my process and some optimization tips. Please keep in mind that my method may not be the best, so if you have any better suggestions, I'm open to discussing them.

there is an example repo: https://github.com/dongwa/quasar-netlify-ssr-demo

Let's dive into the process:

1. Initial Setup

At the outset, there was a scarcity of information on deploying Quasar SSR on Netlify. To overcome this hurdle, I treated the Quasar SSR app as an Express app. This allowed me to leverage information related to Netlify and Express for the deployment.

2. Creating the Netlify Configuration File

To get started, I created a Netlify configuration file named netlify.toml at the root of my project. Here's what the file looks like:

[build]
  # The 'base' specifies the project's root path, where 'npm i' and 'npm run build' will run.
  base = '.'

  # The 'publish' directory is where we'll deploy static assets.
  publish = 'dist/ssr/client'

  # The 'command' field is customizable for the build process.
  command = 'quasar build -m ssr'

[functions]
  # Using Express as an external Node.js module.
  external_node_modules = ["express"]

  # We cannot directly use 'dist/ssr/index.js'  for the following reasons
  directory = 'dist/ssr/netlify/functions'

# Redirects all incoming requests to serverless functions.
[[redirects]]
  force = true
  from = "/*"
  status = 200
  to = "/.netlify/functions/index/:splat"

3. Overcoming Challenges

One of the first challenges I encountered was related to the [functions].directory configuration. Initially, I tried to use dist/ssr/index.js as Netlify's function, but it resulted in an error that said, "index.handler is not defined or not exported." I realized that Netlify requires a JavaScript file structured as follows:

exports.handler = xxxx

However, Quasar's dist/ssr/index.js had a different structure:

exports.default = Promise<handler>

To resolve this, I made changes to the listen function in src-ssr/server.js by removing all async code to eliminate promises like:

import express from 'express'
import compression from 'compression'
import serverless from 'serverless-http'

//...

export function listen ({ app, port, isReady, ssrHandler }) {
  if (process.env.DEV) {
    isReady()
    return app.listen(port, () => {
      if (process.env.PROD) {
        console.log('Server listening at port ' + port)
      }
    })
  } else {
    // 生产环境下：
    return {
      handler: serverless(ssrHandler)
    }
  }
}

and then created a new function, dist/ssr/netlify/functions/index.js, as Netlify's function. Here's what it looks like:

const ssr = require('../../index.js')
exports.handler = ssr.default.handler

4. Managing Clean Builds

Since the dist directory gets cleaned during the build process, I added a script to create the dist/ssr/netlify/functions/index.js file after each build. I accomplished this by editing the quasar.config.js file:

build: {
  afterBuild ({ quasarConf }) {
    // Create the Netlify function
    const distDir = path.resolve(__dirname, quasarConf.build.distDir)
    const netifyFuncDir = path.join(distDir, '/netlify/functions')
    fs.mkdirSync(netifyFuncDir, {
      recursive: true
    })
    const code = 'const ssr = require(\'../../index.js\')\nexports.handler = ssr.default.handler'
    fs.writeFileSync(path.join(netifyFuncDir, 'index.js'), code, {
      encoding: 'utf-8'
    })
  }
}

5. Handling Static Asset Loading

After deploying, I encountered an issue where only the initial HTML page loaded, and all static assets like CSS and JS files were not working as expected.

To be honest, I'm not entirely sure why this happened. In theory, Quasar should already be handling the static file hosting. However, I did find a solution:

To address this, I made some changes to the netlify.toml file by adding specific [[redirects]] rules:

[build]
  base = '.'
  publish = 'dist/ssr/client'
  command = 'quasar build -m ssr'

[functions]
  external_node_modules = ["express"]
  directory = 'dist/ssr/netlify/functions'

[[redirects]]
  force = true 
  from = "/assets/*"
  status = 200
  to = "/assets/:splat"

[[redirects]]
  force = true
  from = "/*"
  status = 200
  to = "/.netlify/functions/index/:splat"

This ensured that client/assets directory would load correctly. However, adding all client files to [[redirects]] was a tedious process.

6. Alternative Redirect Handling

I found an alternative approach to handle redirects by referring to Netlify's documentation. You can save a plain text file called _redirects without a file extension in your site's publish directory. refs https://docs.netlify.com/routing/overview/

To automate this process, I used JavaScript to generate the _redirects file after each build:

afterBuild ({ quasarConf }) {
  // Create the Netlify function
  const distDir = path.resolve(__dirname, quasarConf.build.distDir)
  const netifyFuncDir = path.join(distDir, '/netlify/functions')
  fs.mkdirSync(netifyFuncDir, {
    recursive: true
  })
  const code = 'const ssr = require(\'../../index.js\')\nexports.handler = ssr.default.handler'
  fs.writeFileSync(path.join(netifyFuncDir, 'index.js'), code, {
    encoding: 'utf-8'
  })

  // Create the static resource directory for Netlify
  const clientDir = path.join(distDir, 'client')
  let str = '# Redirects from what the browser requests to what we serve\n'
  const files = fs.readdirSync(clientDir)
  for (const file of files) {
	// I'm using the lazy method here. You should use the fs. stat method to determine if the file is a directory
    if (file.includes('.')) {
      str += `/${file}                        /${file}\n`
    } else {
      str += `/${file}/*                        /${file}/:splat\n`
    }
  }

  fs.writeFileSync(path.join(clientDir, '_redirects'), str, {
    encoding: 'utf-8'
  })
}

After these adjustments, I successfully deployed the application, and everything worked as expected. I hope this information is helpful, and you can now enjoy your fully functional Quasar application on Netlify with SSR mode!

If there are any shortcomings in this article, please feel free to point them out.

2024/2/18 Update

For ease of use, I have encapsulated the above steps as an quasar-app-extension，you can try it:

dongwa/netlify-quasar

2025/5/21 Update

Unfortunately, after the new version of Quasar was migrated to the ESM architecture, this approach no longer worked

If you use @quasar/app-vite v2.0+ with esm, you can try quasar ext add [email protected].

For more info, please ref the extension source code: dongwa/netlify-quasar@c70fc04

[darqus]

thanks, it's work

[dongwa]

For ease of use, I have encapsulated the above steps as an extension，you can try it:

https://github.com/dongwa/netlify-quasar

[EbubeIreneaus]

Thanks alot😎

[dongwa]

Unfortunately, after the new version of Quasar was migrated to the ESM architecture, this approach no longer worked

If you use @quasar/app-vite v2.0+ with esm, you can try quasar ext add [email protected].

For more info, please ref the extension source code: dongwa/netlify-quasar@c70fc04