elm-s3

This package helps make uploading file to Amazon S3 quick and easy.

Install

elm install jaredramirez/elm-s3

Usage

First, you need to create a config for the request. This configuration holds data that's needed across all upload requests, so if you need to upload files in multiple places across your app you can create this config once and use it all over.

import S3


s3Config : S3.Config
s3Config =
    S3.config
        { accessKey = "..." -- AWS Access Key
        , secretKey = "..." -- AWS Secret Key
        , bucket = "my-bucket"
        , region = "us-east-2"
        }
        |> S3.withPrefix "invoices/"

Next, you need to get a file. You can do this with core File package. Take a look at it's documentation to see how to get a file from the user. Once you have it, you can upload the file!

import Http
import File exposing (File)
import S3


type Msg
    = ...
    | FileLoaded File
    | SetFileRequest (Result Http.Error S3.Response)




update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
    case msg of


        ...


        FileLoaded file->
            ( model
            , S3.uploadFile
                { fileName = "customerInvoice.pdf"
                , contentType = "application/pdf"
                , file = file
                }
                s3Config
                SetFileRequest
            )


        SetFileRequest result ->
            case result of
                Err httpError ->
                    -- Handle the error
                    ...


                Ok {location} ->
                    -- Do something with uploaded file path! Maybe display it to the user,
                    -- maybe upload it to your server.
                    -- The world is your oyseter!
                    ...

And that's it!

Note on tracking upload progress

Uploading to S3 requires getting the current time, so this implementation uses Time.now and Task under the hood. Unfortunately, you can't track progress on http tasks. I'm not sure how important this feature is to people. If it a high priority for you, please create an issue and I'll look into adding work around support for it!

S3 Permissions

There's a few things to note about S3 permissions.

Make sure that your user's IAM policy and the bucket policy provides access to the bucket (and path prefix) you want to upload too. Take a look at AWS's docs for a few examples.
If you use this package and run into issues with CORs, try setting the CORs configuration on your bucket to something like:

    <CORSConfiguration>
      <CORSRule>
        <AllowedOrigin>http://myAmazingSite.com</AllowedOrigin>>>
        <AllowedMethod>POST</AllowedMethod>
        <ExposeHeader>ETag</ExposeHeader>
        <ExposeHeader>Location</ExposeHeader>
        <AllowedHeader>\*</AllowedHeader>
      </CORSRule>
    </CORSConfiguration>

Note the AllowedOrigin tag and AllowedHeader tag, which should fix the CORs problem but also make sure to add both the ExposeHeader options. The upload request in this library will fail without them. If you don't have any CORs issues, don't worry about this.

Thanks

Thanks to react-native-aws3! I've used that library before on a react-native app and wanted something similar in Elm. It's the basis for writing this package.

jaredramirez/elm-s3/1.0.1