title	emoji	colorFrom	colorTo	sdk	pinned	license	app_port
Next.js on 🤗 Spaces	🐳🤗	blue	yellow	docker	false	agpl-3.0	3000

Next.js on 🤗 Spaces

Run your ML demo with ease in a Next.js environment

At failfast, we're passionate about crafting demos with TypeScript, Next.js, and MUI. Inspired by the ease-of-use of Gradio and Streamlit within Hugging Face Spaces, we aim to deliver a similar developer experience to JavaScript enthusiasts. Our toolkit includes predefined MUI components, empowering you to build intuitive UIs for your ML demos.

---

• Local development
  • Use the Docker container locally
• Secret Management
  • Build-time
  • Runtime
• Dockerize an existing project
• Sync your GitHub repository with your 🤗 Space
• Cleanup your 🤗 Space
• Development Roadmap

---

Local development

1. Install the dependencies: npm i
2. Start the local dev-server: npm run dev
3. Open the app via localhost:3000

Use the Docker container locally

ℹ️ In order for the commands to work, you need at least Docker >= 20.10, as we use env-variables as secrets

To make sure that everything is working out, you can run your container locally:

1. Install Docker on your machine
2. Go into the nextjs-hf-spaces folder
3. Build your Docker image: docker build -t nextjs-hf-spaces .
4. Run your Docker container: docker run -p 3000:3000 nextjs-hf-spaces.
5. Open the app via localhost:3000

If you also have a secret that needs to be passed into the container, you can do this:

1. Create a copy of .env.local.example and rename it to .env.local (it contains the secret HF_EXAMPLE_SECRET)
2. Run your Docker container and specify the env-file: docker run -p 3000:3000 --env-file .env.local nextjs-hf-spaces
3. Open the example API via localhost:3000/api/env and see that the value of our secret HF_EXAMPLE_SECRET is shown

Secret Management

To not expose your secrets to end users, you can add them directly in Settings of your 🤗 Space.

1. Open your space and navigate to the Settings
2. Find Repository secrets & click on New secret

That's it, you can now access your secret.

Build-time

If you need to have a secret during build-time (e.g. you want to install private npm packages), then you can add this directly into the Dockerfile:

# Uncomment the following lines if you want to use a secret at buildtime, 
# for example to access your private npm packages
RUN --mount=type=secret,id=HF_EXAMPLE_SECRET,mode=0444,required=true \
    $(cat /run/secrets/HF_EXAMPLE_SECRET)

In this case, we mount the secret HF_EXAMPLE_SECRET (using Docker secrets) inside and can use it.

Runtime

When your 🤗 Space is running and you want to use a secret (e.g. access an API that requires authentication) without exposing it to the user, you can use it as an environment variable via process.env.

import process from "node:process";
import { NextApiRequest, NextApiResponse } from "next";

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  const exampleSecret = process.env.HF_EXAMPLE_SECRET;

  // Your logic to access an API that requires authentication

  return response.status(200).json("We have access to an external API");
}

A simple example can be found at nextjs-hf-spaces/api/env. This will return the secret to see that it's working, but you wouldn't do this in your space, as you don't want to expose the secret to an end user.

Dockerize an existing project

To add support for Docker to an existing project, just copy the Dockerfile into the root of the project and add the following to the next.config.js file:

// next.config.js
module.exports = {
  // ... rest of the configuration.
  output: "standalone",
};

This will build the project as a standalone app inside the Docker image.

Sync your GitHub repository with your 🤗 Space

If you want to use all the features for collaborative development on GitHub, but keep your demo on 🤗 Spaces, then you can set up a GitHub action that will automatically push changes from GitHub into Spaces.

ℹ️ Git-LFS is required for files bigger than 10MB

1. Create your repo on GitHub
2. Create a Github secret named HF_TOKEN and use an access token from Hugging Face as its value (you must be logged in to do this)
3. Update the workflow sync_to_hf_spaces.yml
   • Configure HF_USERNAME: Replace failfast with the name of your 🤗 user account or your 🤗 organization
   • Configure HF_SPACE_NAME: Replace nextjs-hf-spaces with the name of your 🤗 space
4. Push the code into your repo on GitHub

This should force push changes in the main branch from GitHub into your 🤗 space.

For further information, you can check out the guide on Hugging Face.

Cleanup your 🤗 Space

You don't need all the demo content and examples? Then you can delete these resources to get a clean 🤗 Space:

• src/pages/api/env.ts
• src/components/example-components.tsx
• src/components/getting-started.tsx
• src/components/under-construction.tsx
• src/components/title.tsx
• src/components/huggingface/huggingface.tsx

Update the src/components/index.tsx and remove:

<Title />

<GettingStarted />

<DividerBox />

<ExampleComponents />

i Got an idea how this could be better? Please let us know!

Development Roadmap

The next milestones in no particular order are:

• Components for all @huggingface/inference methods (WIP)
• Components to use langchain.js
• Components to use hyv
• Publish components on npm to make them usable outside of nextjs-hf-spaces
• Provide templates for different use-cases, that are too complex for single components
• Docs on how to use the components with all available options

i Anything missing? Please let us know!