feat: added base components, updated the readme, extended summarization

Author: TimPietrusky

.env.local.example

@@ -0,0 +1 @@
+HF_EXAMPLE_SECRET=thisisjustanexample

.gitignore

@@ -32,4 +32,7 @@ yarn-error.log*
 
 # typescript
 *.tsbuildinfo
-next-env.d.ts
+next-env.d.ts
+
+# Docker secrets used for local dev
+.secrets

Dockerfile

@@ -15,6 +15,10 @@ RUN \
   else echo "Lockfile not found." && exit 1; \
   fi
 
+# 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)
 
 # Rebuild the source code only when needed
 FROM base AS builder

README.md

@@ -1,6 +1,6 @@
 ---
 title: "Next.js on \U0001F917 Spaces"
-emoji: "🐳🤗"
+emoji: "\U0001F433\U0001F917"
 colorFrom: blue
 colorTo: yellow
 sdk: docker
@@ -10,14 +10,25 @@ app_port: 3000
 ---
 <h1 align="center">Next.js on 🤗 Spaces</h1>
 
-This starter can be used to run [Next.js](https://nextjs.org/) using [Docker](https://huggingface.co/docs/hub/spaces-sdks-docker) on 🤗 [Spaces](https://huggingface.co/spaces).
+<p align="center">
+Run your ML demo with ease in a <a href="https://nextjs.org">Next.js</a> environment
+</p>
+
+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.
+
+---
 
 <!-- toc -->
 
 - [Local development](#local-development)
-- [Use the Docker container locally](#use-the-docker-container-locally)
+  * [Use the Docker container locally](#use-the-docker-container-locally)
+- [Secret Management](#secret-management)
+  * [Build-time](#build-time)
+  * [Runtime](#runtime)
 - [Dockerize an existing project](#dockerize-an-existing-project)
-- [Manage your 🤗 Space via GitHub](#manage-your-%F0%9F%A4%97-space-via-github)
+- [Sync your GitHub repository with your 🤗 Space](#sync-your-github-repository-with-your-%F0%9F%A4%97-space)
+- [Cleanup your 🤗 Space](#cleanup-your-%F0%9F%A4%97-space)
+- [Development Roadmap](#development-roadmap)
 
 <!-- tocstop -->
 
@@ -29,16 +40,68 @@ This starter can be used to run [Next.js](https://nextjs.org/) using [Docker](ht
 2. Start the local dev-server: `npm run dev`
 3. Open the app via [localhost:3000](http://localhost:3000)
 
-## Use the Docker container locally
+### 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](https://docs.docker.com/get-docker/) on your machine
 2. Go into the `nextjs-hf-spaces` folder
-3. Build your Docker image: `docker build -t nextjs-hf-spaces .`.
+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](http://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](http://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`:
+
+```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](https://docs.docker.com/engine/swarm/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`. 
+
+```typescript
+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](https://huggingface.co/spaces/failfast/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:
@@ -53,9 +116,9 @@ module.exports = {
 
 This will build the project as a standalone app inside the Docker image.
 
-## Manage your 🤗 Space via GitHub
+## 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.
+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
 
@@ -71,3 +134,42 @@ This should force push changes in the **main** branch from GitHub into your 🤗
 For further information, you can check out the [guide on Hugging Face](https://huggingface.co/docs/hub/spaces-github-actions).
 
 
+## 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:
+
+```jsx
+<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`](https://huggingface.co/docs/huggingface.js/inference/README) methods (WIP)
+* Components to use [langchain.js](https://js.langchain.com/docs)
+* Components to use [hyv](https://github.com/failfa-st/hyv)
+* Publish components on npm to make them usable outside of [nextjs-hf-spaces](https://github.com/failfa-st/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!
+
+

package-lock.json

@@ -1,12 +1,13 @@
 {
-  "name": "nextjs-docker-starter",
-  "version": "1.0.0",
-  "description": "Run your ML demo app using Next.js on 🤗 Spaces",
+  "name": "nextjs-hf-spaces",
+  "version": "0.0.1",
+  "description": "Run your ML demo with ease in a Next.js environment",
   "keywords": [
     "nextjs",
     "artificial intelligence",
     "javascript",
-    "hugging face spaces",
+    "typescript",
+    "hugging face",
     "machine learning"
   ],
   "license": "MIT",
@@ -15,11 +16,11 @@
     "url": "https://github.com/TimPietrusky"
   },
   "scripts": {
-    "dev": "next dev",
     "build": "next build",
-    "start": "next start",
+    "dev": "next dev",
     "lint": "next lint",
     "spj": "npx sort-package-json",
+    "start": "next start",
     "toc": "npx markdown-toc README.md -i"
   },
   "dependencies": {

package.json

@@ -3,12 +3,11 @@ import { styled } from "@mui/material/styles";
 
 export const SectionBox = styled(Paper)<PaperProps>(({ theme }) => ({
   display: "flex",
-  alignItems: "center",
-  justifyContent: "center",
   padding: 15,
-  border: `5px solid transparent`,
-  borderImage: `linear-gradient(to bottom right, #b827fc 0%, #2c90fc 25%, #b8fd33 50%, #fec837 75%, #fd1892 100%)`,
-  borderImageSlice: 1,
+  paddingTop: 30,
+  paddingBottom: 30,
+  marginBottom: 20,
+  background: `linear-gradient(to bottom right, ${theme.palette.primary.main} 0%, ${theme.palette.secondary.main} 100%)`,
 }));
 
 export const HighlightBox = styled(Paper)<PaperProps>(({ theme }) => ({

src/components/boxes.tsx src/components/base/boxes.tsx

@@ -0,0 +1,19 @@
+import { styled } from "@mui/material/styles";
+import { Paper, PaperProps } from "@mui/material";
+
+type CodeProps = {
+  children: string;
+};
+
+const CodeBox = styled(Paper)<PaperProps>(({ theme }) => ({
+  fontFamily: "monospace",
+  padding: 8,
+  borderTop: `2px solid ${theme.palette.secondary.dark}`,
+  borderBottom: `2px solid ${theme.palette.secondary.dark}`,
+}));
+
+export default function Code(props: CodeProps) {
+  const { children } = props;
+
+  return <CodeBox>{children}</CodeBox>;
+}

src/components/base/code.tsx

@@ -0,0 +1,41 @@
+import { Button, Typography } from "@mui/material";
+import { MouseEventHandler } from "react";
+
+interface ExampleButtonProps {
+  text: string;
+  displayLength?: number;
+  onClick?: (text: string) => void;
+}
+
+/**
+ *
+ * A button that hosts an example "text" that can be used as the input
+ * to anything to get an inspiration on how to get started.
+ *
+ * @param props ExampleButtonProps
+ * @returns
+ */
+export default function ExampleButton(props: ExampleButtonProps) {
+  const { text, displayLength = 50, onClick } = props;
+
+  const displayText =
+    text.slice(0, displayLength) + (text.length > displayLength ? "..." : "");
+
+  const handleClick: MouseEventHandler = event => {
+    event.preventDefault();
+
+    if (onClick) {
+      onClick(text);
+    }
+  };
+
+  return (
+    <Button
+      onClick={handleClick}
+      sx={{ textTransform: "none" }}
+      variant="outlined"
+    >
+      <Typography>{displayText}</Typography>
+    </Button>
+  );
+}

src/components/base/example-button.tsx

@@ -0,0 +1,56 @@
+import { KeyboardArrowDown, KeyboardArrowUp } from "@mui/icons-material";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  Collapse,
+  IconButton,
+  Stack,
+} from "@mui/material";
+import { ReactElement, useState } from "react";
+
+type OptionsProps = {
+  children: ReactElement | ReactElement[];
+  opened?: boolean;
+};
+
+/**
+ *  Define options that are hidden by default
+ *
+ * @param props OptionsProps
+ * @param props.opened boolean - Are the options visible or not (default)
+ *
+ * @returns Options
+ */
+export default function Options(props: OptionsProps) {
+  const { children, opened = false } = props;
+
+  const [showOptions, setShowOptions] = useState(opened);
+
+  const handleShowOptions = () => setShowOptions(!showOptions);
+
+  return (
+    <>
+      <Card>
+        <CardHeader
+          title="Options"
+          onClick={handleShowOptions}
+          action={
+            <IconButton aria-label="expand" size="small">
+              {showOptions ? <KeyboardArrowUp /> : <KeyboardArrowDown />}
+            </IconButton>
+          }
+          sx={{
+            cursor: "pointer",
+          }}
+          titleTypographyProps={{ variant: "h6", sx: { fontSize: "1em" } }}
+        />
+        <Collapse in={showOptions}>
+          <CardContent>
+            <Stack spacing={2}>{children}</Stack>
+          </CardContent>
+        </Collapse>
+      </Card>
+    </>
+  );
+}

src/components/base/options.tsx

@@ -0,0 +1,22 @@
+import {
+  Box,
+  FormControlLabel,
+  Slider,
+  SliderProps,
+  Typography,
+} from "@mui/material";
+
+type SliderWithLabelProps = SliderProps & {
+  label?: string;
+};
+
+export default function SliderWithLabel(props: SliderWithLabelProps) {
+  const { label = "", valueLabelDisplay = "auto" } = props;
+
+  return (
+    <Box>
+      <Typography variant="subtitle1">{label}</Typography>
+      <Slider {...props} valueLabelDisplay={valueLabelDisplay} />
+    </Box>
+  );
+}