How to Upload Files and Update List Items in SharePoint with SPFx and PnPJS v4: A Simple Guide

Quick Intro

For SharePoint solutions, storing files and their metadata is always necessary. Therefore, we use the SharePoint Document Library to store files and their metadata. Performing this task through the SharePoint UX is much easier. However, when you build an SPFx application with file upload and metadata-storing capabilities, you should know how to upload files and update list items in SharePoint. This blog covers all of these aspects.

Prerequisites:

Before starting with the implementation, ensure you have the following prerequisites:

• An SPFx Project
• PnPjs v4 installed & configured

How to upload files to the folders in document library?

1. Ensure Folder Existence: Before uploading any files to the folders inside the document library, it is always good practice to check whether a folder exists or not.

   • I have a function that checks for the existence of a folder by using the folder path.
   • If the folder doesn’t exist, I have another function that creates the folder.

1
    // Make sure you have the folder available before uploading files
2
    export const ensureFolder = async (uploadPath: string) => {
3
      let sp: SPFI = getSP()
4
      const folder = await sp.web
5
        .getFolderByServerRelativePath(uploadPath)
6
        .select("Exists")()
7

8
    // Calls createFolder if the folder doesn't exists
9
      if (!folder.Exists) {
10
        await createFolder(uploadPath)
11
      }
12
    }
13

14
    // Function to create folder
15
    export const createFolder = async (folderPath: any) => {
16
      let sp: SPFI = getSP()
17

18
      // creates a new folder for web with specified server relative url
19
      await sp.web.folders.addUsingPath(folderPath)
20
    }

2. Create a for loop. Since we are uploading multiple files, we need to iterate over each file and upload it.

   1
    for (const file of files) {
   2
        try {
   3
          const fileNamePath = encodeURI(file.name)
   4
          let result: any
   5
   
   6
          if (file.size <= 10485760) {
   7
            // 3. Small upload (less than 10MB)
   8
            await sp.web
   9
              .getFolderByServerRelativePath(basePath)
   10
              .files.addUsingPath(fileNamePath, file, { Overwrite: true })
   11
          } else {
   12
            // 4. Large upload (greater than 10MB)
   13
            await sp.web
   14
              .getFolderByServerRelativePath(basePath)
   15
              .files.addChunked(fileNamePath, file, {
   16
                progress: (data) => {
   17
                  console.log(`Upload progress: ${data}%`)
   18
                },
   19
                Overwrite: true,
   20
              })
   21
          }
   22
    }

   1. if condition checking file size, cause uploading larger files in straight isn’t ideal. So file size less than 10mb we use addUsingPath() method otherwise addChunked().

💡

Use of encodeURI() - When dealing with file or folder names containing special characters (spaces, #, %, &, etc.), SharePoint paths require encoding to ensure they are correctly interpreted by the API.

PnPjs provides two methods for file uploads: addUsingPath() and addChunked().

• addUsingPath() – Ideal for uploading smaller files. It supports file names containing percent (%) or pound (#) characters.

• addChunked() – Ideal for uploading larger files, as it uses a chunking method to upload the file in smaller parts. Internally, it uses three methods:

  1. It starts with addUsingPath() to add the file metadata without uploading the actual file (the file length remains 0 initially).
  2. Then, it internally calls startUpload() → continueUpload() → finishUpload().
  3. After finishUpload() is called, the file length is updated in the response.

💡

The addChunked() method provides a third argument, which is a progress callback. This can be used to create a file upload progress bar for better UX.

3. Now the final code looks like below:

   1
    import { getSP } from "../utils/spUtility"
   2
    import { SPFI } from "@pnp/sp"
   3
   
   4
    // Make sure you have the folder available before uploading files
   5
    export const ensureFolder = async (uploadPath: string) => {
   6
      let sp: SPFI = getSP()
   7
      const folder = await sp.web
   8
        .getFolderByServerRelativePath(uploadPath)
   9
        .select("Exists")()
   10
   
   11
    // Calls createFolder if the folder doesn't exists
   12
      if (!folder.Exists) {
   13
        await createFolder(uploadPath)
   14
      }
   15
    }
   16
   
   17
    // Function to create folder
   18
    export const createFolder = async (folderPath: any) => {
   19
      let sp: SPFI = getSP()
   20
   
   21
      // creates a new folder for web with specified server relative url
   22
      await sp.web.folders.addUsingPath(folderPath)
   23
    }
   24
   
   25
    export const uploadFiles = async (
   26
      files: File[],
   27
      pageContext: any,
   28
      category: string
   29
    ) => {
   30
      let sp: SPFI = getSP()
   31
      let results: any[] = []
   32
   
   33
      // Create base path for uploads
   34
      let basePath = `${pageContext._site.serverRelativeUrl}/Documents/dummyFolder`
   35
   
   36
      // 1. Ensure folder exists
   37
      await ensureFolder(basePath)
   38
   
   39
      // 2. Process each file
   40
      for (const file of files) {
   41
        try {
   42
          const fileNamePath = encodeURI(file.name)
   43
   
   44
          if (file.size <= 10485760) {
   45
            // 3. Small upload (less than 10MB)
   46
            await sp.web
   47
              .getFolderByServerRelativePath(basePath)
   48
              .files.addUsingPath(fileNamePath, file, { Overwrite: true })
   49
          } else {
   50
            // 4. Large upload (greater than 10MB)
   51
            await sp.web
   52
              .getFolderByServerRelativePath(basePath)
   53
              .files.addChunked(fileNamePath, file, {
   54
                progress: (data) => {
   55
                  console.log(`Upload progress: ${data}%`)
   56
                },
   57
                Overwrite: true,
   58
              })
   59
          }
   60
        } catch (error) {
   61
          console.error(`Error uploading file ${file.name}:`, error)
   62
        }
   63
      }
   64
   
   65
      return results
   66
    }

Now that you understand how to upload files efficiently to a SharePoint document library, let’s move on to updating items after the file upload.

Updating Metadata After File Upload

To update the metadata or additional properties of files after uploading them, we use the getFileByServerRelativePath() method. This method takes the server-relative URL of the file (from the response of the file upload), retrieves the item, and allows us to update the metadata.

Lets see it in action:

1
let fileInfo = await sp.web.getFileByServerRelativePath(result.ServerRelativeUrl).getItem()
2

3
await fileInfo.update({
4
 Category: category;
5
})

Here’s is the final code:

1
import { getSP } from "../utils/spUtility"
2
import { SPFI } from "@pnp/sp"
3

4
// Make sure you have the folder available before uploading files
5
export const ensureFolder = async (uploadPath: string) => {
6
  let sp: SPFI = getSP()
7
  const folder = await sp.web
8
    .getFolderByServerRelativePath(uploadPath)
9
    .select("Exists")()
10

11
// Calls createFolder if the folder doesn't exists
12
  if (!folder.Exists) {
13
    await createFolder(uploadPath)
14
  }
15
}
16

17
// Function to create folder
18
export const createFolder = async (folderPath: any) => {
19
  let sp: SPFI = getSP()
20

21
  // creates a new folder for web with specified server relative url
22
  await sp.web.folders.addUsingPath(folderPath)
23
}
24

25
export const uploadFiles = async (
26
  files: File[],
27
  pageContext: any,
28
  category: string
29
) => {
30
  let sp: SPFI = getSP()
31
  let results: any[] = []
32

33
  // Create base path for uploads
34
  let basePath = `${pageContext._site.serverRelativeUrl}/Documents/dummyFolder`
35

36
  // 1. Ensure folder exists
37
  await ensureFolder(basePath)
38

39
  // 2. Process each file
40
  for (const file of files) {
41
    try {
42
      const fileNamePath = encodeURI(file.name)
43
      let result: any
44

45
      if (file.size <= 10485760) {
46
        // 3. Small upload (less than 10MB)
47
        result = await sp.web
48
          .getFolderByServerRelativePath(basePath)
49
          .files.addUsingPath(fileNamePath, file, { Overwrite: true })
50
      } else {
51
        // 4. Large upload (greater than 10MB)
52
        result = await sp.web
53
          .getFolderByServerRelativePath(basePath)
54
          .files.addChunked(fileNamePath, file, {
55
            progress: (data) => {
56
              console.log(`Upload progress: ${data}%`)
57
            },
58
            Overwrite: true,
59
          })
60
      }
61
      let fileInfo = await sp.web.getFileByServerRelativePath(result.ServerRelativeUrl).getItem()
62

63
      await fileInfo.update({
64
         Category: category;
65
      })
66
    } catch (error) {
67
      console.error(`Error uploading file ${file.name}:`, error)
68
    }
69
  }
70
  return results
71
}

Conclusion

With this blog, we have learned how to upload files and update their metadata in a SharePoint document library using SPFx and PnPjs. We have also explored some good practices to use & how the addUsingPath() and addChunked() methods work, including the behind-the-scenes process.

Happy Coding 🚀